www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Adding Markdown to Ddoc

reply Walter Bright <newshound2 digitalmars.com> writes:
https://help.github.com/articles/basic-writing-and-formatting-syntax/

Anyone interested in picking up the flag?

(I know this has come up before, and I've been opposed to it, but I've changed 
my mind.)
Dec 05 2017
next sibling parent rikki cattermole <rikki cattermole.co.nz> writes:
We should probably do the opposite.

Build a markdown parser and then have a way to give the output an 
understanding of ddoc features.

It will also be usable in other projects ;)
Dec 05 2017
prev sibling next sibling parent reply Mike Parker <aldacron gmail.com> writes:
On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 
wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
Can you see me jumping up and down over here? I don't care about it for source documentation, but if we could start using Mardkown in place of Ddoc macros for the web site, woohoo!
Dec 05 2017
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/5/2017 8:37 PM, Mike Parker wrote:
 Can you see me jumping up and down over here?
No, but my seismometer is showing some action!
Dec 05 2017
prev sibling next sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig+d outerproduct.org> writes:
Am 06.12.2017 um 05:11 schrieb Walter Bright:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
 
 Anyone interested in picking up the flag?
 
 (I know this has come up before, and I've been opposed to it, but I've 
 changed my mind.)
This is great news! While I don't have the time to work on this directly, I can offer vibe.d's Markdown module* (re-licensing as necessary): https://github.com/vibe-d/vibe.d/blob/master/textfilter/vibe/textfilter/markdown.d Markdown is a strange thing to parse in the classical way due to its original regex-cascade style of implementation/design, so it was kind of difficult to find representations that allow reasonably efficient and comprehensible processing. * There is also "dmarkdown", which is just a fork of the vibe.d code
Dec 06 2017
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/6/2017 1:33 AM, Sönke Ludwig wrote:
 This is great news! While I don't have the time to work on this directly, I
can 
 offer vibe.d's Markdown module* (re-licensing as necessary): 
 https://github.com/vibe-d/vibe.d/blob/master/textfilter/vibe/textfilter/markdown.d
 
 Markdown is a strange thing to parse in the classical way due to its original 
 regex-cascade style of implementation/design, so it was kind of difficult to 
 find representations that allow reasonably efficient and comprehensible
processing.
 
 * There is also "dmarkdown", which is just a fork of the vibe.d code
Thanks! It's always great to be able to leverage existing code. But you'll need to Boost license it!
Dec 06 2017
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig+d outerproduct.org> writes:
Am 06.12.2017 um 12:34 schrieb Walter Bright:
 On 12/6/2017 1:33 AM, Sönke Ludwig wrote:
 This is great news! While I don't have the time to work on this 
 directly, I can offer vibe.d's Markdown module* (re-licensing as 
 necessary): 
 https://github.com/vibe-d/vibe.d/blob/master/textfilter/vibe/t
xtfilter/markdown.d 


 Markdown is a strange thing to parse in the classical way due to its 
 original regex-cascade style of implementation/design, so it was kind 
 of difficult to find representations that allow reasonably efficient 
 and comprehensible processing.

 * There is also "dmarkdown", which is just a fork of the vibe.d code
Thanks! It's always great to be able to leverage existing code. But you'll need to Boost license it!
No problem!
Dec 06 2017
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/6/2017 3:37 AM, Sönke Ludwig wrote:
 No problem!
Now, just need someone to step up and do the work. :-/
Dec 06 2017
prev sibling parent Ecstatic Coder <ecstatic.coder gmail.com> writes:
On Wednesday, 6 December 2017 at 09:33:47 UTC, Sönke Ludwig wrote:
 Am 06.12.2017 um 05:11 schrieb Walter Bright:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
 
 Anyone interested in picking up the flag?
 
 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
This is great news! While I don't have the time to work on this directly, I can offer vibe.d's Markdown module* (re-licensing as necessary): https://github.com/vibe-d/vibe.d/blob/master/textfilter/vibe/textfilter/markdown.d Markdown is a strange thing to parse in the classical way due to its original regex-cascade style of implementation/design, so it was kind of difficult to find representations that allow reasonably efficient and comprehensible processing. * There is also "dmarkdown", which is just a fork of the vibe.d code
For those interested, I've also written a parser for a Markdon-like syntax (Pendown). You can find it here : https://github.com/senselogic/PENDOWN Yeah I know, everybody is gonna say "why reinvent Markdown, it's already perfect, it's the best invention since Cherry Coke, etc". But sorry, obviously it wasn't perfect for my needs. I was REALLY tired of several flaws and limitations in the Markdown syntax, so I wrote this tool and quickly converted all my Mardown files to the Pendown format. Maybe some people won't like its syntax because it's NOT a Markdown clone, but I use it all the time for all my personal notes, and now I would NEVER switch back to Markdown. I use it even for those notes I eventually need to print on paper actually. Personally I mostly use the JavaScript version by editing an HTML document, but the D version could be what you are looking for, used as a tool or as a library. As usual, I've made the code as simple as it could be, and it's licensed under the GPL3, so maybe you should have a look at it before deciding to use the well-known (but far from perfect) Markdown syntax.
Dec 16 2017
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/5/2017 8:11 PM, Walter Bright wrote:
 (I know this has come up before, and I've been opposed to it, but I've changed 
 my mind.)
Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
Dec 06 2017
parent reply Adrian Matoga <dlang.spam matoga.info> writes:
On Wednesday, 6 December 2017 at 12:13:56 UTC, Walter Bright 
wrote:
 On 12/5/2017 8:11 PM, Walter Bright wrote:
 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)
Dec 06 2017
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 12/6/17 8:24 AM, Adrian Matoga wrote:
 On Wednesday, 6 December 2017 at 12:13:56 UTC, Walter Bright wrote:
 On 12/5/2017 8:11 PM, Walter Bright wrote:
 (I know this has come up before, and I've been opposed to it, but 
 I've changed my mind.)
Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)
Yes, please! -Steve
Dec 06 2017
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Dec 06, 2017 at 10:32:38AM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
 On 12/6/17 8:24 AM, Adrian Matoga wrote:
 On Wednesday, 6 December 2017 at 12:13:56 UTC, Walter Bright wrote:
 On 12/5/2017 8:11 PM, Walter Bright wrote:
 (I know this has come up before, and I've been opposed to it,
 but I've changed my mind.)
Part of this change of mind was driven by the bit of markdown that Ddoc already supports - the backticks to quote code and auto detection of URLs - and how nice that has turned out.
This is going to be the right time to deprecate the automatic change of some words that happen to be parameter names into code. :)
Yes, please!
[...] +1000! This "feature" has been the source of countless Phobos and dlang.org bugs, leading to time-wasting churn of changing `someword` into `_someword`, just to suppress the automatic change. The underscore proliferation makes the source code quite unreadable if your module happens to be unfortunate enough to have many symbols that coincide with actual words. It even happens inside URL macros used extensively in Phobos, meaning that you have to mangle your URLs just so DDoc doesn't destroy them by inserting "helpful" macro syntax, but that has the unfortunate side-effect of making DDoc URLs non-copy-pasteable when editing the source code. In short, the "helpful" automatic changing of words into code has turned out to be a total disaster in practice. For every instance where it's actually helpful, there are 99 instances where it's a nuisance. It's time to admit that it was a bad design, and kill it with fire and extreme prejudice. T -- Без труда не выловишь и рыбку из пруда.
Dec 06 2017
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/06/2017 01:14 PM, H. S. Teoh wrote:
 This "feature" has been the source of countless Phobos and dlang.org
 bugs, leading to time-wasting churn of changing `someword` into
 `_someword`, just to suppress the automatic change.
Isn't that controlled via a macro? We should just redefine the macro to return its argument unchanged. -- Andrei
Dec 06 2017
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Dec 06, 2017 at 02:42:49PM -0500, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/06/2017 01:14 PM, H. S. Teoh wrote:
 This "feature" has been the source of countless Phobos and dlang.org
 bugs, leading to time-wasting churn of changing `someword` into
 `_someword`, just to suppress the automatic change.
Isn't that controlled via a macro? We should just redefine the macro to return its argument unchanged. -- Andrei
Yes, the macro is DDOC_PARAM. However, this macro is emitted from two places in ddmd/doc.d: one in highlightText(), where we'd like to suppress it, and the other in highlightCode(), where we WANT the highlighting. Ergo, there is no way to selectively disable it only in running text without also killing any highlighting it may have had in code snippets, where it is wanted. Perhaps a possible workaround is to use a shim in highlightText(), say, instead of using DDOC_PARAM, have it emit DDOC_PARAM_IN_TEXT, the latter of which passes its argument to DDOC_PARAM. Then to selectively disable it, we simply redefine DDOC_PARAM_IN_TEXT to return the parameter unchanged. (And highlightCode() will continue to emit DDOC_PARAM directly, so the highlighting will still work in code snippets.) This fancy dance seems completely redundant, though. If we wanted to highlight the parameter in running text, we can already use the new backtick syntax `paramName`. There's really no added value in introducing yet another default macro DDOC_PARAM_IN_TEXT with a default definition that, most of the time, people don't even want anyway. T -- They pretend to pay us, and we pretend to work. -- Russian saying
Dec 06 2017
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/6/2017 5:24 AM, Adrian Matoga wrote:
 This is going to be the right time to deprecate the automatic change of some 
 words that happen to be parameter names into code. :)
Let's please keep that as a completely separate discussion, as the issue is orthogonal.
Dec 06 2017
prev sibling next sibling parent reply Nemanja Boric <4burgos gmail.com> writes:
On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 
wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.
Dec 06 2017
parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 12/6/17 6:41 AM, Nemanja Boric wrote:
 On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, but I've 
 changed my mind.)
These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.
Speaking of that tool, I suspect Ddoc's Markdown support will have to do the same as harboured-mod does with respect to the bits of Markdown syntax that are already claimed by Ddoc [1] [1] https://github.com/dlang-community/harbored-mod#differences-from-vanilla-markdown
Dec 06 2017
parent Basile B. <b2.temp gmx.com> writes:
On Wednesday, 6 December 2017 at 15:08:53 UTC, David Gileadi 
wrote:
 On 12/6/17 6:41 AM, Nemanja Boric wrote:
 On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 
 wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
These are great news. We are using harbored-mod (https://github.com/dlang-community/harbored-mod) which does this for quite some time, but it feels like a second-class citizen compared to the ddoc.
Speaking of that tool, I suspect Ddoc's Markdown support will have to do the same as harboured-mod does with respect to the bits of Markdown syntax that are already claimed by Ddoc [1] [1] https://github.com/dlang-community/harbored-mod#differences-from-vanilla-markdown
The markdown lib used in harbored-mod comes from vibe-d (renamed as dmarkdown), so it will likely automatically be the case, see this part of the discussion: https://forum.dlang.org/post/p08kpm$oag$1 digitalmars.com
Dec 06 2017
prev sibling next sibling parent David Gileadi <gileadisNOSPM gmail.com> writes:
On 12/5/17 9:11 PM, Walter Bright wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
 
 Anyone interested in picking up the flag?
 
 (I know this has come up before, and I've been opposed to it, but I've 
 changed my mind.)
I didn't notice anyone pick this up yet. I'm taking a stab at it, writing it mostly from scratch. However if someone else wants to pick it up you're very welcome; my attempt is likely to be slow, especially this time of year :)
Dec 06 2017
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2017-12-06 05:11, Walter Bright wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
 
 Anyone interested in picking up the flag?
 
 (I know this has come up before, and I've been opposed to it, but I've 
 changed my mind.)
Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension? -- /Jacob Carlborg
Dec 07 2017
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/7/2017 2:21 AM, Jacob Carlborg wrote:
 On 2017-12-06 05:11, Walter Bright wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, but I've changed 
 my mind.)
Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension?
I dunno. Make a case. There's no backward compatibility necessary, so we do not have to worry about the two ways of doing lists, for example. Just '*' will do. Aside from what Ddoc already does, I'd just stick with: * Lists * Nested Lists * Headings * Bold * Italic * \ escaping * Quoted text and skip: * tables * links * emoji
Dec 07 2017
parent reply Jacob Carlborg <doob me.com> writes:
On 2017-12-08 06:35, Walter Bright wrote:

 I dunno. Make a case. There's no backward compatibility necessary, so we 
 do not have to worry about the two ways of doing lists, for example. 
 Just '*' will do.
 
 Aside from what Ddoc already does, I'd just stick with:
 
 * Lists
 * Nested Lists
 * Headings
 * Bold
 * Italic
 * \ escaping
 * Quoted text
 
 and skip:
 
 * tables
 * links
 * emoji
I think links are pretty important, or do you prefer to use Ddoc macros for that? I think we should try to support standard markdown [2] plus features from GitHub markdown. Like fenced code blocks and syntax highlighting [3]. For simplicity we can start by only supporting D syntax highlighting. Just for the record, the link you included in your original post [1], contains some non-standard markdown like: * Task lists * Mentioning people and teams * Referencing issues and pull requests * Using emoji [1] https://help.github.com/articles/basic-writing-and-formatting-syntax [2] https://daringfireball.net/projects/markdown/syntax [3] https://help.github.com/articles/creating-and-highlighting-code-blocks/ -- /Jacob Carlborg
Dec 08 2017
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 I think links are pretty important, or do you prefer to use Ddoc macros for
that?
I just don't see much of any improvement of markdown over LINK2.
 I think we should try to support standard markdown [2]
Unfortunately, there's really no such thing. But as I said, we do have an advantage as Ddoc will not likely be importing existing markdown text from elsewhere, so there's little impetus for compatibility. There's no point to supporting multiple unordered list syntaxes, for example.
 plus features from GitHub 
 markdown. Like fenced code blocks and syntax highlighting [3]. For simplicity
we 
 can start by only supporting D syntax highlighting.
Ddoc already does code blocks and syntax highlighting.
 Just for the record, the link you included in your original post [1], contains 
 some non-standard markdown like:
I know. That's why I produced a list.
 * Task lists
Not relevant for Ddoc.
 * Mentioning people and teams
Not relevant for Ddoc.
 * Referencing issues and pull requests
LINK2
 * Using emoji
The problem with these is where are the images stored? So no.
Dec 08 2017
next sibling parent reply Seb <seb wilzba.ch> writes:
On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
Dec 08 2017
next sibling parent reply WebFreak001 <d.forum webfreak.org> writes:
On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
 On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
pls no emoji support, it's not a unified experience across devices, they should just die out lol
Dec 08 2017
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 12/8/17 7:42 AM, WebFreak001 wrote:
 On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
 On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
pls no emoji support, it's not a unified experience across devices, they should just die out lol
+1000, I can't imagine why you'd want emoji in your documentation. -Steve
Dec 08 2017
next sibling parent reply Patrick Schluter <Patrick.Schluter bbox.fr> writes:
On Friday, 8 December 2017 at 15:53:41 UTC, Steven Schveighoffer 
wrote:
 On 12/8/17 7:42 AM, WebFreak001 wrote:
 On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
 On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright 
 wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
pls no emoji support, it's not a unified experience across devices, they should just die out lol
+1000, I can't imagine why you'd want emoji in your documentation.
The poop emoji is quite useful to comment other peoples code :-)
Dec 08 2017
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 12/8/17 12:09 PM, Patrick Schluter wrote:
 On Friday, 8 December 2017 at 15:53:41 UTC, Steven Schveighoffer wrote:
 On 12/8/17 7:42 AM, WebFreak001 wrote:
 On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
 On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
pls no emoji support, it's not a unified experience across devices, they should just die out lol
+1000, I can't imagine why you'd want emoji in your documentation.
The poop emoji is quite useful to comment other peoples code :-)
It would be your own code that would have it, as it's the documentation for your functions :) -Steve
Dec 08 2017
parent Patrick Schluter <Patrick.Schluter bbox.fr> writes:
On Friday, 8 December 2017 at 18:11:56 UTC, Steven Schveighoffer 
wrote:
 On 12/8/17 12:09 PM, Patrick Schluter wrote:
 On Friday, 8 December 2017 at 15:53:41 UTC, Steven 
 Schveighoffer wrote:
 On 12/8/17 7:42 AM, WebFreak001 wrote:
 On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
 [...]
pls no emoji support, it's not a unified experience across devices, they should just die out lol
+1000, I can't imagine why you'd want emoji in your documentation.
The poop emoji is quite useful to comment other peoples code :-)
It would be your own code that would have it, as it's the documentation for your functions :)
That's where it's the most appropriate! (says the one who just corrected two regressions in his project that go back to 2013).
Dec 08 2017
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/8/2017 7:53 AM, Steven Schveighoffer wrote:
 +1000, I can't imagine why you'd want emoji in your documentation.
No D-Man emoji, sigh.
Dec 08 2017
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Dec 08, 2017 at 05:38:21PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/8/2017 7:53 AM, Steven Schveighoffer wrote:
 +1000, I can't imagine why you'd want emoji in your documentation.
No D-Man emoji, sigh.
We should lobby the Unicode Consortium to add it! T -- Never step over a puddle, always step around it. Chances are that whatever made it is still dripping.
Dec 08 2017
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/8/2017 3:10 AM, Seb wrote:
 On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 * Using emoji
The problem with these is where are the images stored? So no.
Someone thought it's a great idea, to include them into Unicode: https://unicode.org/emoji/charts/full-emoji-list.html
Thanks for the link, I didn't know that browsers supported them yet. If you want to use them, just use the existing syntax to do it: \u25B6 right arrow D already has support for lots of named entities: https://dlang.org/spec/entity.html There doesn't seem much point in adding a third method of naming entities. Besides, you can always create a macro to name them anything you please: RIGHTARROW=\u25B6 and use it: $(RIGHTARROW)
Dec 08 2017
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Dec 08, 2017 at 05:34:31PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/8/2017 3:10 AM, Seb wrote:
[...]
 https://unicode.org/emoji/charts/full-emoji-list.html
Thanks for the link, I didn't know that browsers supported them yet. If you want to use them, just use the existing syntax to do it: \u25B6 right arrow D already has support for lots of named entities: https://dlang.org/spec/entity.html There doesn't seem much point in adding a third method of naming entities. Besides, you can always create a macro to name them anything you please: RIGHTARROW=\u25B6 and use it: $(RIGHTARROW)
Yeah, I think emojis are not worth adding special syntax for. They are just too much effort for something marginal to documenting code, that we shouldn't be wasting time trying to support them or debate about them. T -- Food and laptops don't mix.
Dec 08 2017
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2017-12-08 11:13, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
 I think links are pretty important, or do you prefer to use Ddoc 
 macros for that?
I just don't see much of any improvement of markdown over LINK2.
 I think we should try to support standard markdown [2]
Unfortunately, there's really no such thing.
No, there's no official standard but there is a subset that most Markdown implementation support [1]. If we would like to claim that Ddoc supports Markdown then I think we need to support that subset, even though there already exist a corresponding Ddoc syntax. Otherwise it will be confusing and very hard to remember which features are supported with Markdown syntax and which are not.
 But as I said, we do have 
 an advantage as Ddoc will not likely be importing existing markdown text 
 from elsewhere, so there's little impetus for compatibility. There's no 
 point to supporting multiple unordered list syntaxes, for example.
Well, if you claim that Ddoc supports Markdown syntax then people will expect all of it to work.
 plus features from GitHub markdown. Like fenced code blocks and syntax 
 highlighting [3]. For simplicity we can start by only supporting D 
 syntax highlighting.
Ddoc already does code blocks and syntax highlighting.
Yes, but people will be more familiar with Markdown than with Ddoc.
 Just for the record, the link you included in your original post [1], 
 contains some non-standard markdown like:
I know. That's why I produced a list.
 * Task lists
Not relevant for Ddoc.
This might be useful if Ddoc is used for other things than documentation for programming APIs, like we use for dlang.org. But I agree.
 * Using emoji
The problem with these is where are the images stored? So no.
There are no images stored. Emojis are part of the Unicode standard, so the only thing that is needed is a proper Unicode font. But I don't think we need it. BTW, GitHub has a specification for their Markdown implementation [2] [1] https://daringfireball.net/projects/markdown/syntax [2] https://github.github.com/gfm/ -- /Jacob Carlborg
Dec 08 2017
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
 Otherwise it will be confusing and very hard 
 to remember which features are supported with Markdown syntax and which are
not.
This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
Dec 08 2017
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2017-12-09 02:49, Walter Bright wrote:

 This is way overstating the case. Ddoc already supports some markdown, 
 and some markdown in different ways.
Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax. -- /Jacob Carlborg
Dec 09 2017
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/9/2017 12:23 PM, Jacob Carlborg wrote:
 On 2017-12-09 02:49, Walter Bright wrote:
 
 This is way overstating the case. Ddoc already supports some markdown, and 
 some markdown in different ways.
Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax.
There isn't any, because officially saying Markdown is supported is too vague. There is no Markdown standard. But what Ddoc does do should be officially documented, and is as far as I know.
Dec 09 2017
parent reply meppl <mephisto nordhoff-online.de> writes:
On Sunday, 10 December 2017 at 01:19:13 UTC, Walter Bright wrote:
 On 12/9/2017 12:23 PM, Jacob Carlborg wrote:
 On 2017-12-09 02:49, Walter Bright wrote:
 
 This is way overstating the case. Ddoc already supports some 
 markdown, and some markdown in different ways.
Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax.
There isn't any, because officially saying Markdown is supported is too vague. There is no Markdown standard. But what Ddoc does do should be officially documented, and is as far as I know.
since commonmark exists, is specified and is compatibale to many markdown-languages, I claim there is a markdown standard: http://spec.commonmark.org/ commonmark is the common denominator of the markdown-languages.
Dec 09 2017
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/9/2017 9:17 PM, meppl wrote:
 since commonmark exists, is specified and is compatibale to many 
 markdown-languages,  I claim there is a markdown standard: 
 http://spec.commonmark.org/
It certainly wants to be the standard, but until most everyone decides to follow it, it is not. There is no list of anyone on that site conforming to it. Besides, commonmark has a lot of stuff we don't need, like multiple ways of doing the same thing.
Dec 09 2017
next sibling parent reply meppl <mephisto nordhoff-online.de> writes:
On Sunday, 10 December 2017 at 06:20:43 UTC, Walter Bright wrote:
 On 12/9/2017 9:17 PM, meppl wrote:
 since commonmark exists, is specified and is compatibale to 
 many markdown-languages,  I claim there is a markdown 
 standard: http://spec.commonmark.org/
It certainly wants to be the standard, but until most everyone decides to follow it, it is not. There is no list of anyone on that site conforming to it.
I think these are wrong criterias to estimate the value of commonmark. Commonmark doesn't need to list anyone and doesn't need to be listed by anyone to be a standard. commonmark is a standard proven by following "facts": 1) whenever a language feature is used by all popular markdown languages, it is standard 2) there are markdown features who are used by all popular markdown languages 3) everyone can reveal this matter of fact - e.g. by writing it down as a specification 4) any language feature published by the commonmark-spec is used by all popular markdown languages ergo: commonmark == standard markdown well, at least, if the commonmark people did their homework right
 Besides, commonmark has a lot of stuff we don't need, like 
 multiple ways of doing the same thing.
I am not the one who is implementing it, so I will not argue against this.
Dec 10 2017
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/10/2017 6:22 AM, meppl wrote:
 I think these are wrong criterias to estimate the value of commonmark. 
 Commonmark doesn't need to list anyone and doesn't need to be listed by anyone 
 to be a standard. commonmark is a standard proven by following "facts":
 1) whenever a language feature is used by all popular markdown languages, it
is 
 standard
 2) there are markdown features who are used by all popular markdown languages
 3) everyone can reveal this matter of fact - e.g. by writing it down as a 
 specification
 4) any language feature published by the commonmark-spec is used by all
popular 
 markdown languages
 ergo: commonmark == standard markdown
 well, at least, if the commonmark people did their homework right
I have a more pragmatic definition of a standard: 1. Products that implement it say they adhere to it and defer to it as the authority on correct behavior. 2. There's more than one such product. 3. There's more products adhering to that standard than some other competing standard. So far as I know, commonmarkdown satisfies zero of those. Don't get me wrong, I think commonmarkdown is a worthy effort, and is definitely in the running to be a standard. Certainly a lot more effort seems to have been put into it vs other markdowns. It is entirely reasonable to refer to it to answer questions about whether some detail should yin or yang. But implementing commonmarkdown in Ddoc is not what we're going to do, at least for the near term.
Dec 10 2017
next sibling parent reply Jakob Bornecrantz <wallbraker gmail.com> writes:
On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:
 On 12/10/2017 6:22 AM, meppl wrote:
 I think these are wrong criterias to estimate the value of 
 commonmark. Commonmark doesn't need to list anyone and doesn't 
 need to be listed by anyone to be a standard. commonmark is a 
 standard proven by following "facts":
 1) whenever a language feature is used by all popular markdown 
 languages, it is standard
 2) there are markdown features who are used by all popular 
 markdown languages
 3) everyone can reveal this matter of fact - e.g. by writing 
 it down as a specification
 4) any language feature published by the commonmark-spec is 
 used by all popular markdown languages
 ergo: commonmark == standard markdown
 well, at least, if the commonmark people did their homework 
 right
I have a more pragmatic definition of a standard: 1. Products that implement it say they adhere to it and defer to it as the authority on correct behavior. 2. There's more than one such product. 3. There's more products adhering to that standard than some other competing standard. So far as I know, commonmarkdown satisfies zero of those. Don't get me wrong, I think commonmarkdown is a worthy effort, and is definitely in the running to be a standard. Certainly a lot more effort seems to have been put into it vs other markdowns. It is entirely reasonable to refer to it to answer questions about whether some detail should yin or yang. But implementing commonmarkdown in Ddoc is not what we're going to do, at least for the near term.
There are loads of implementations of CommonMark https://github.com/commonmark/CommonMark/wiki/List-of-Common ark-Implementations the one I have written is not listed. That covers 1 and 2. Also Markdown is not a standard, it started out as a pearl script and the a short documentation on how to write text for it. It has several ambiguities, leading to a lot of implementations do things differently. So they don't agree on the authority of Markdown. Which makes Markdown a mess because you don't know what behaviour you will get from the different implementation. So that covers 3. And to add more, CommonMark on the other hand has a full spec written and several test that covers the difficult to get right parts of Markdown/CommonMark. I'm sure I don't need to tell you the virtues of a good test suit. Cheers, Jakob.
Dec 11 2017
next sibling parent reply Guillaume Piolat <first.last gmail.com> writes:
On Monday, 11 December 2017 at 14:22:37 UTC, Jakob Bornecrantz 
wrote:
 And to add more, CommonMark on the other hand has a full spec 
 written and several test that covers the difficult to get right 
 parts of Markdown/CommonMark. I'm sure I don't need to tell you 
 the virtues of a good test suit.
The CommonMark approach is to just take the union of all possible features and call it a day. Standards without opinions don't deserve to be implemented by anyone.
Dec 11 2017
next sibling parent user1234 <user1234 12.nl> writes:
On Monday, 11 December 2017 at 15:45:07 UTC, Guillaume Piolat 
wrote:
 On Monday, 11 December 2017 at 14:22:37 UTC, Jakob Bornecrantz 
 wrote:
 And to add more, CommonMark on the other hand has a full spec 
 written and several test that covers the difficult to get 
 right parts of Markdown/CommonMark. I'm sure I don't need to 
 tell you the virtues of a good test suit.
The CommonMark approach is to just take the union of all possible features and call it a day. Standards without opinions don't deserve to be implemented by anyone.
It's crazy to see that the most basic HTML features still cause issues in Markdown. CommonMark can be seen as a pragmatic approach but may suffer from the "Babel tower" problem: try to assemble all the languages tend to make everybody disagree, leading exactly to the opposite of the initial goal, that is unification (it's probably not exactly that but i'm not a theologist after all, 😂).
Dec 11 2017
prev sibling next sibling parent John Gabriele <jgabriele fastmail.fm> writes:
On Monday, 11 December 2017 at 15:45:07 UTC, Guillaume Piolat 
wrote:
 The CommonMark approach is to just take the union of all 
 possible features and call it a day.
 Standards without opinions don't deserve to be implemented by 
 anyone.
I disagree. If anything, it's more of a subset of features common to the most widely-used markdown implementations, with corner cases ironed out (see lots of discussion on the [CommonMark forum](https://talk.commonmark.org/), and also comparisons of output from different implementations at [Babelmark2](http://johnmacfarlane.net/babelmark2/) (linked to from commonmark.org)).
Dec 11 2017
prev sibling parent Patrick Schluter <Patrick.Schluter bbox.fr> writes:
On Monday, 11 December 2017 at 15:45:07 UTC, Guillaume Piolat 
wrote:
 On Monday, 11 December 2017 at 14:22:37 UTC, Jakob Bornecrantz 
 wrote:
 And to add more, CommonMark on the other hand has a full spec 
 written and several test that covers the difficult to get 
 right parts of Markdown/CommonMark. I'm sure I don't need to 
 tell you the virtues of a good test suit.
The CommonMark approach is to just take the union of all possible features and call it a day. Standards without opinions don't deserve to be implemented by anyone.
To me, it sounds more to that https://xkcd.com/927/
Dec 11 2017
prev sibling next sibling parent bachmeier <no spam.net> writes:
On Monday, 11 December 2017 at 14:22:37 UTC, Jakob Bornecrantz 
wrote:
 There are loads of implementations of CommonMark 
 https://github.com/commonmark/CommonMark/wiki/List-of-Common
ark-Implementations the one I have written is not listed. That covers 1 and 2.

 Also Markdown is not a standard, it started out as a pearl 
 script and the a short documentation on how to write text for 
 it. It has several ambiguities, leading to a lot of 
 implementations do things differently. So they don't agree on 
 the authority of Markdown. Which makes Markdown a mess because 
 you don't know what behaviour you will get from the different 
 implementation. So that covers 3.

 And to add more, CommonMark on the other hand has a full spec 
 written and several test that covers the difficult to get right 
 parts of Markdown/CommonMark. I'm sure I don't need to tell you 
 the virtues of a good test suit.

 Cheers, Jakob.
If there is a desire to add CommonMark support, it is best to output ddoc to commonmark and call an external tool specified by the user. The proposal to add a few markdown features to ddoc is a reasonable short run goal. If you set commonmark support as a goal, it will probably never get done.
Dec 11 2017
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/11/2017 6:22 AM, Jakob Bornecrantz wrote:
 There are loads of implementations of CommonMark 
 https://github.com/commonmark/CommonMark/wiki/List-of-Common
ark-Implementations 
They appear to be libraries that offer an implementation. Does the Markdown used in github, reddit, wikipedia, doxygen, etc., use any of those libraries?
 the one I have written is not listed. That covers 1 and 2.
I didn't know you wrote one. There are 3 Markdown packages on Dub: https://code.dlang.org/search?q=markdown and I don't see your name on them. I strongly recommend you register yours with Dub (if it is in D) and on the commonmark site!
Dec 11 2017
next sibling parent David Gileadi <gileadisNOSPM gmail.com> writes:
On 12/11/17 1:45 PM, Walter Bright wrote:
 On 12/11/2017 6:22 AM, Jakob Bornecrantz wrote:
 There are loads of implementations of CommonMark 
 https://github.com/commonmark/CommonMark/wiki/List-of-Common
ark-Implementations 
They appear to be libraries that offer an implementation. Does the Markdown used in github, reddit, wikipedia, doxygen, etc., use any of those libraries?
It appears that github now uses their own fork of cmark, which adds support for tables, etc. [1] [1] https://githubengineering.com/a-formal-spec-for-github-markdown/
Dec 11 2017
prev sibling parent reply Jakob Bornecrantz <wallbraker gmail.com> writes:
On Monday, 11 December 2017 at 20:45:38 UTC, Walter Bright wrote:
 On 12/11/2017 6:22 AM, Jakob Bornecrantz wrote:
 There are loads of implementations of CommonMark 
 https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations
They appear to be libraries that offer an implementation. Does the Markdown used in github, reddit, wikipedia, doxygen, etc., use any of those libraries?
Github in the past used something called Github Flavored Markdown, which was Markdown + whatever quirks where in the ruby implementation of Markdown + Tables. Not Markdown. The same with all of the others, they all had different quirks because the markdown "spec" was bad. Let me use a different technology as a analogy. Walter: We should use HTML for DDOC! Others: Cool, but can you use CommonTML (HTML5), it has this cool spec and actual tests that make sure it looks the same, and that the code you have written is robust. HTML isn't really a standard as such, you are not sure what you get and there is no agreed upon testsuit, so you aren't even sure you get the same results with different versions of your own code. Walter: Is this used elsewhere? I really want HTML. Others: Here is the spec and a bunch of implementations. Walter: But HTML is more common, its used in Netscape Navigator and IE6. Others: *collective headdesk* What I'm trying to get at is, use the testsuit and spec, it will save you lot of other problems down the road. And you will be making the world of Markdown a better place because there will be one less implementation that does things slightly differently.
 the one I have written is not listed. That covers 1 and 2.
I didn't know you wrote one. There are 3 Markdown packages on Dub: https://code.dlang.org/search?q=markdown and I don't see your name on them. I strongly recommend you register yours with Dub (if it is in D) and on the commonmark site!
It is not written in D, but the language is close enough in concepts that it can be mechanically ported into D, and is licensed under BOOST. Feel free to do what ever to it[1]. We first used the markdown parser from vibe.d, when we threw the CommonMark testsuit, 10 tests segfaulted and 1 infinite-spun in a loop somewhere in the code. We then rewrote from scratch using the recommended practices from the CommonMark spec and the XML output from cmark as a guide. The code is used in our documentation system. Both doc-comments and outside documentation files are written in CommonMark. The doc-comments uses Doxygen tags which is then run through CommonMark, most of the time it does nothing to the comments, but if you want to write long comments it makes it much more natural and enjoyable. [1] https://github.com/VoltLang/Watt/tree/master/markdown/src/watt/markdown
Dec 11 2017
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/11/2017 2:30 PM, Jakob Bornecrantz wrote:
 What I'm trying to get at is, use the testsuit and spec, it will save you lot
of 
 other problems down the road. And you will be making the world of Markdown a 
 better place because there will be one less implementation that does things 
 slightly differently.
Perhaps you missed that I wrote this twice now: "Don't get me wrong, I think commonmarkdown is a worthy effort, and is definitely in the running to be a standard. Certainly a lot more effort seems to have been put into it vs other markdowns. It is entirely reasonable to refer to it to answer questions about whether some detail should yin or yang."
Dec 11 2017
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/11/2017 2:30 PM, Jakob Bornecrantz wrote:
 It is not written in D, but the language is close enough in concepts that it
can 
 be mechanically ported into D, and is licensed under BOOST. Feel free to do
what 
 ever to it[1].
Thank you for Boost licensing it!
 We first used the markdown parser from vibe.d, when we threw the CommonMark 
 testsuit, 10 tests segfaulted and 1 infinite-spun in a loop somewhere in the 
 code. We then rewrote from scratch using the recommended practices from the 
 CommonMark spec and the XML output from cmark as a guide.
 
 The code is used in our documentation system. Both doc-comments and outside 
 documentation files are written in CommonMark. The doc-comments uses Doxygen 
 tags which is then run through CommonMark, most of the time it does nothing to 
 the comments, but if you want to write long comments it makes it much more 
 natural and enjoyable.
 
 [1] https://github.com/VoltLang/Watt/tree/master/markdown/src/watt/markdown
It's apparently written in Volt: https://github.com/VoltLang/Watt But the two links there to Volt are dead: https://github.com/VoltLang/Watt/blob/master/volt-lang.org
Dec 11 2017
next sibling parent Bernard Helyer <b.helyer gmail.com> writes:
On Tuesday, 12 December 2017 at 02:30:39 UTC, Walter Bright wrote:
 It's apparently written in Volt:

 https://github.com/VoltLang/Watt

 But the two links there to Volt are dead:

 https://github.com/VoltLang/Watt/blob/master/volt-lang.org
Ah, the joys of forgetting too ensure URLs in Markdown READMEs are absolute. The correct link is volt-lang.org -- I have fixed that README also, thanks for pointing it out.
Dec 11 2017
prev sibling parent reply Jakob Bornecrantz <wallbraker gmail.com> writes:
On Tuesday, 12 December 2017 at 02:30:39 UTC, Walter Bright wrote:
 On 12/11/2017 2:30 PM, Jakob Bornecrantz wrote:
 It is not written in D, but the language is close enough in 
 concepts that it can be mechanically ported into D, and is 
 licensed under BOOST. Feel free to do what ever to it[1].
Thank you for Boost licensing it!
Happy if it can help you in anyway. We have imported some code from Druntime/Phobos as well, so licensing it all under BOOST made sense.
 We first used the markdown parser from vibe.d, when we threw 
 the CommonMark testsuit, 10 tests segfaulted and 1 
 infinite-spun in a loop somewhere in the code. We then rewrote 
 from scratch using the recommended practices from the 
 CommonMark spec and the XML output from cmark as a guide.
 
 The code is used in our documentation system. Both 
 doc-comments and outside documentation files are written in 
 CommonMark. The doc-comments uses Doxygen tags which is then 
 run through CommonMark, most of the time it does nothing to 
 the comments, but if you want to write long comments it makes 
 it much more natural and enjoyable.
 
 [1] 
 https://github.com/VoltLang/Watt/tree/master/markdown/src/watt/markdown
It's apparently written in Volt: https://github.com/VoltLang/Watt
It's a language a small group of people (me included) have been working on for a while, I avoid naming it here because it's a system level language like D. I don't want to advertise it in any form here to keep the discussion on D. But in this case the intent was code sharing. :D Cheers, Jakob.
Dec 12 2017
parent reply Chris <wendlec tcd.ie> writes:
On Tuesday, 12 December 2017 at 18:14:18 UTC, Jakob Bornecrantz 
wrote:

 It's a language a small group of people (me included) have been 
 working on for a while, I avoid naming it here because it's a 
 system level language like D. I don't want to advertise it in 
 any form here to keep the discussion on D.

 But in this case the intent was code sharing. :D

 Cheers, Jakob.
From a first (superficial) glance it looks like D in drag :-)
Dec 14 2017
parent Ecstatic Coder <ecstatic.coder gmail.com> writes:
On Thursday, 14 December 2017 at 10:39:02 UTC, Chris wrote:
 On Tuesday, 12 December 2017 at 18:14:18 UTC, Jakob Bornecrantz 
 wrote:

 It's a language a small group of people (me included) have 
 been working on for a while, I avoid naming it here because 
 it's a system level language like D. I don't want to advertise 
 it in any form here to keep the discussion on D.

 But in this case the intent was code sharing. :D

 Cheers, Jakob.
From a first (superficial) glance it looks like D in drag :-)
Once reimplemented in C++, Volt has actually the potential to become a VERY successful scripting language for video games, because the D-like syntax itself is actually a great selling point, since D allows both low-level (structs, etc) and high-level (reference classes, etc) programming, which is EXACTLY what video game scripts need.
Dec 19 2017
prev sibling next sibling parent reply John Gabriele <jgabriele fastmail.fm> writes:
On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:

 Don't get me wrong, I think commonmarkdown is a worthy effort, 
 and is definitely in the running to be a standard. Certainly a 
 lot more effort seems to have been put into it vs other 
 markdowns.
Note that CommonMark isn't simply a markdown implementation. It's a: * spec * test suite * two reference implementations * collection of community implementations and also includes an active community forum. The people involved are dedicated. The spec is conservative, uncontroversial, and detailed.
 But implementing commonmarkdown in Ddoc is not what we're going 
 to do, at least for the near term.
Right. That said, if you want to add a handful of markdown-ish features, I think it would be most useful to draw your very limited markdown subset from the CommonMark markdown spec. The other option takes you down the road of unintentionally creating yet another variant for users to contend with.
Dec 11 2017
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/11/2017 11:29 AM, John Gabriele wrote:
 Right. That said, if you want to add a handful of markdown-ish features, I
think 
 it would be most useful to draw your very limited markdown subset from the 
 CommonMark markdown spec. The other option takes you down the road of 
 unintentionally creating yet another variant for users to contend with.
That's basically what I said :-)
Dec 11 2017
prev sibling next sibling parent reply Chris <wendlec tcd.ie> writes:
On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:
 I have a more pragmatic definition of a standard:

 1. Products that implement it say they adhere to it and defer 
 to it as the authority on correct behavior.

 2. There's more than one such product.
You have to start somewhere. Somebody has to put the second product out there.
 3. There's more products adhering to that standard than some 
 other competing standard.
"In 2017, GitHub released a formal specification of their GitHub Flavored Markdown (GFM) that is based on CommonMark.[32] It follows the CommonMark specification exactly except for tables, strikethrough, autolinks and task lists, which the GitHub spec has added as extensions[33]. GitHub also changed the parser used on their sites accordingly, which required some documents to be changed, e.g. a space after the hash signs of a heading is now required." (https://en.wikipedia.org/wiki/Markdown#GFM) If GitHub is not some sort of "standard" or at least a good indicator of where things are going, I don't know what is. So basically, CommonMark is the standard for GitHub. It merely added some extensions that are useful for GitHub related stuff. This means that millions of programmers are already familiar with CommonMark and use it on a daily basis. This in turn would make it easier for them to read and contribute to D source code. Sometimes simple things like that can be the straw that breaks the camel's back (and Ddocs certainly put people off (including me)).
 So far as I know, commonmarkdown satisfies zero of those.

 Don't get me wrong, I think commonmarkdown is a worthy effort, 
 and is definitely in the running to be a standard. Certainly a 
 lot more effort seems to have been put into it vs other 
 markdowns. It is entirely reasonable to refer to it to answer 
 questions about whether some detail should yin or yang.

 But implementing commonmarkdown in Ddoc is not what we're going 
 to do, at least for the near term.
Hm. I'd really give it a second thought.
Dec 12 2017
parent Chris <wendlec tcd.ie> writes:
Compare:

Output:
https://github.com/vibe-d/vibe.d/blob/master/README.md

Input:
https://raw.githubusercontent.com/vibe-d/vibe.d/master/README.md

Most programmers who use GitHub will be familiar with this and 
can write docs, tutorials etc. with very little effort. The set 
of Markdown used for the D documentation shouldn't be needlessly 
limited (i.e. it shouldn't offer less than CommonMark - GitHub's 
core markup langauge).
Dec 12 2017
prev sibling parent reply John Gabriele <jgabriele fastmail.fm> writes:
On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:
 I have a more pragmatic definition of a standard:

 1. Products that implement it say they adhere to it and defer 
 to it as the authority on correct behavior.

 2. There's more than one such product.

 3. There's more products adhering to that standard than some 
 other competing standard.

 So far as I know, commonmarkdown satisfies zero of those.
Looks like Stack Exchange is working on standardizing on CommonMark: <https://meta.stackexchange.com/questions/238957/will-commonmark-be-adopted-for-se/258587#258587>
Dec 12 2017
parent John Gabriele <jgabriele fastmail.fm> writes:
On Tuesday, 12 December 2017 at 15:59:42 UTC, John Gabriele wrote:
 On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright 
 wrote:
 I have a more pragmatic definition of a standard:

 1. Products that implement it say they adhere to it and defer 
 to it as the authority on correct behavior.

 2. There's more than one such product.

 3. There's more products adhering to that standard than some 
 other competing standard.

 So far as I know, commonmarkdown satisfies zero of those.
Looks like Stack Exchange is working on standardizing on CommonMark: <https://meta.stackexchange.com/questions/238957/will-commonmark-be-adopted-for-se/258587#258587>
Rust is as well: <https://github.com/rust-lang/rust/issues/44229>.
Dec 12 2017
prev sibling parent Chris <wendlec tcd.ie> writes:
On Sunday, 10 December 2017 at 06:20:43 UTC, Walter Bright wrote:

 Besides, commonmark has a lot of stuff we don't need, like 
 multiple ways of doing the same thing.
We would have to come with style guidelines to avoid a mix of say: *italic* and _italic_ # Heading 1 and Heading 1 ========== But that shouldn't be too hard. Just a few months of bikeshedding :-)
Dec 12 2017
prev sibling parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 12/8/17 6:49 PM, Walter Bright wrote:
 On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
 Otherwise it will be confusing and very hard to remember which 
 features are supported with Markdown syntax and which are not.
This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph. I'd like to support as many Markdown features as we can, but there will always be a some differences--particularly those that conflict with existing DDoc features.
Dec 09 2017
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 9 December 2017 at 21:05:04 UTC, David Gileadi wrote:
 For instance, as I've been working on adding Markdown features 
 I was surprised to discover that DDoc's current support for 
 backtick-delimited code only works within a single line. Most 
 implementations I've seen allow it to span hard-wrapped lines, 
 as long as it's within a single paragraph.
I kinda object to calling the ddoc `` thing markdown, since that wasn't the intention. When I added it, I had exactly one goal: be able to write `<xml samples>` in ddoc without it breaking the html output. At the same time, I didn't want it to accidentally trigger if someone pasted a linker error in their doc: undefined reference to `foo' undefined reference to `bar' So it was limited to a single line and required a matching ` to trigger the new code. Then, btw, it does NOT just wrap it in a $(BACKTICK) macro. It first *escapes the string*, for example turning < into &lt;, etc, THEN wraps it in the macro. Though, the reason it uses ` as the delimiter is because markdown does it so it looks familiar... but it wasn't actually based on a desire to be markdown. Similarly, my adrdox thing has some markdown-ish features, but it is explicitly NOT markdown, giving me the freedom to avoid brain damage. (I am not a fan of markdown, it is such a mess and hard to write.)
Dec 09 2017
parent David Gileadi <gileadisNOSPM gmail.com> writes:
On 12/9/17 2:25 PM, Adam D. Ruppe wrote:
 On Saturday, 9 December 2017 at 21:05:04 UTC, David Gileadi wrote:
 For instance, as I've been working on adding Markdown features I was 
 surprised to discover that DDoc's current support for 
 backtick-delimited code only works within a single line. Most 
 implementations I've seen allow it to span hard-wrapped lines, as long 
 as it's within a single paragraph.
I kinda object to calling the ddoc `` thing markdown, since that wasn't the intention. When I added it, I had exactly one goal: be able to write `<xml samples>` in ddoc without it breaking the html output. At the same time, I didn't want it to accidentally trigger if someone pasted a linker error in their doc: undefined reference to `foo' undefined reference to `bar' So it was limited to a single line and required a matching ` to trigger the new code. Then, btw, it does NOT just wrap it in a $(BACKTICK) macro. It first *escapes the string*, for example turning < into &lt;, etc, THEN wraps it in the macro. Though, the reason it uses ` as the delimiter is because markdown does it so it looks familiar... but it wasn't actually based on a desire to be markdown. Similarly, my adrdox thing has some markdown-ish features, but it is explicitly NOT markdown, giving me the freedom to avoid brain damage. (I am not a fan of markdown, it is such a mess and hard to write.)
That makes sense--thanks for the background. To be fair to markdown, it does also require matching backticks and escapes < and > within backtick-quoted sections. But I agree that some markdown "features" are rather messy.
Dec 09 2017
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/9/2017 1:05 PM, David Gileadi wrote:
 On 12/8/17 6:49 PM, Walter Bright wrote:
 On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
 Otherwise it will be confusing and very hard to remember which features are 
 supported with Markdown syntax and which are not.
This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph.
The: --- code --- is for multiline code blocks.
 I'd like to support as many Markdown features as we can,
Only the ones that make good sense for Ddoc, not as many as technically possible.
 but there will always 
 be a some differences--particularly those that conflict with existing DDoc 
 features.
Yes, and keep in mind there is no such thing as standard Markdown. Every implementation has significant differences.
Dec 09 2017
prev sibling next sibling parent reply John Gabriele <jgabriele fastmail.fm> writes:
On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:


 I think we should try to support standard markdown [2]
Unfortunately, there's really no such thing.
Well, the main standardization effort is [CommonMark](http://commonmark.org/). They have a spec, test suite, and reference implementations in C and in JS. There's also a list of other implementations: <https://github.com/commonmark/CommonMark/wiki/List-of-CommonM rk-Implementations> (though D isn't there yet), as well as a community forum. Here's [their 10-minute Markdown tutorial](http://commonmark.org/help/). If going forward with a rolling your own limited markdown version, go with a subset of CommonMark. That subset could always grow into a full implementation of CommonMark if that's desired later on.
Dec 08 2017
parent John Gabriele <jgabriele fastmail.fm> writes:
On Friday, 8 December 2017 at 16:43:56 UTC, John Gabriele wrote:
 If going forward with a rolling your own limited markdown 
 version, go with a subset of CommonMark.
Sorry, typo, that should be, "consider going with".
Dec 08 2017
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Dec 08, 2017 at 02:13:28AM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
[...]
 * Using emoji
The problem with these is where are the images stored? So no.
Unicode contains emoji blocks, which are increasingly commonly used nowadays. But I agree that we should NOT include emoji in Ddoc markdown. Why would anyone want to use emoji in code documentation anyway? Besides, if they *really* want to, they could just insert the actual Unicode character into the documentation text and be done with it. No need for special syntax just for that. Hooray for built-in Unicode support in D! T -- They say that "guns don't kill people, people kill people." Well I think the gun helps. If you just stood there and yelled BANG, I don't think you'd kill too many people. -- Eddie Izzard, Dressed to Kill
Dec 08 2017
prev sibling parent "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 12/08/2017 05:13 AM, Walter Bright wrote:
 
 I just don't see much of any improvement of markdown over LINK2.
 
I do.
Dec 10 2017
prev sibling parent reply Arjan <arjan ask.me.to> writes:
On Thursday, 7 December 2017 at 10:21:21 UTC, Jacob Carlborg 
wrote:
 On 2017-12-06 05:11, Walter Bright wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
 
 Anyone interested in picking up the flag?
 
 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension?
Dang! And there you have it: endless complains and issues about the choosen flavour comming ahead of us now... :-( I would suggest: AsciiDoc! Why? see:http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
Dec 08 2017
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/8/2017 1:49 AM, Arjan wrote:
 Dang! And there you have it: endless complains and issues about the choosen 
 flavour comming ahead of us now... :-(
Naturally. Just Say No :-)
 I would suggest: AsciiDoc! Why? 
 see:http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
Yes, well, we don't have to be compatible with 15 different flavors of Markdown, and we've got Ddoc macros for extensions. I only proposed Markdown for the very small number of cases already listed, and no more. Should probably start with a DIP for it.
Dec 08 2017
prev sibling next sibling parent John Gabriele <jgabriele fastmail.fm> writes:
On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 
wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, 
 but I've changed my mind.)
Great to hear this! :) [Pandoc](http://pandoc.org/) is an excellent widely-used markdown implementation to emulate (or use directly); they support thoughtful additional syntax for definition lists, tables, mathematics, and a few other niceties (including syntax highlighting for D code blocks).
Dec 07 2017
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 
wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/
I think you'll find it is easier said than done to get sane output given existing ddoc pages. My adrdox does some of this special syntax and to maintain compatibility with Phobos, I had to do some recursive action inside macros and ddoc sections to keep the generated html from being totally bogus. Of course, if you're willing to do some cleanup work on the Phobos source code, this can be greatly simplified too (indeed, for adrdox, i did fork some of it, but keeping it up to date was actually harder as a fork than just adding another hack to my parser, so i went that way too). https://help.github.com/articles/basic-writing-and-formatting-syntax/#paragraphs-and-line-breaks this rule in particular takes quite a bit to make sane with ddoc hybrid stuff! PS of course yall could also just surrender to me and use my superior system. I'm not actually a fan of markdown syntax though so i don't quite follow it and do other custom extensions which has rustled some feathers in the past.
Dec 07 2017
prev sibling parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Tuesday, December 05, 2017 20:11:33 Walter Bright via Digitalmars-d 
wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, but I've
 changed my mind.)
I confess that looking over that page, I don't see much reason to add any of it to ddoc. It all seems like stuff that we can already trivially do in ddoc, and most (all?) of it is stuff that already has built-in macros. What are we really trying to gain here? In my experience, the problems with ddoc tend to stem from the fact that it's a general purpose macro language and not just intended for documentation generation - there's nothing built-in for generating links to symbols or a navigation bar like dlang.org has, and while some of it can be done in ddoc with a bit of work, some of it requires additional scripts or programs to do it (e.g. while you can add a macro to create a link for a symbol if you have a website layout designed for it, no macro will be able to generate a navigation bar with the list of modules in the project; you need a separate program to generate the list for you, even if that list is then in ddoc). I really do like ddoc as a macro language, but the fact that that's all it is does hamper it for documentation generation, and while you can get decent, basic documentation out of the box, you can't get anything like doxygen or ddox gives you. You just have separate modules pages without any links to anything or anything indicating what the list of modules is. And you can't even take what's done for Phobos and sanely reuse it, because it's gotten so complicated and is so thoroughly tied to dlang.org. At the moment, I'm actually trying to put together a basic set of ddoc files with a simple program for using dmd to generate the documentation (as opposed to using a separate generator like ddox does) so that I have something relatively simple that I can reuse across projects that will allow my to link documentation with macros like we do in Phobos and have the navigation bar out of the box - hopefully in a way that's reasonably understood and customizable as opposed to the mess that Phobos' documentation generation has become. I suspect that 90+% of folks that generate documentation just use ddox at this point, because making straight ddoc look good is a royal pain right now - at least if you want to be able to reasonably navigate among the documentation pages (or even within a page) as opposed to just reading the documentation for a single module from top to bottom. As for markdown, I fail to see how adding any of it to ddoc would really help anything, since as far as I can tell, ddoc already does what markdown does just with macros instead of whatever combination of stray syntax that markdown uses for different things. And I certainly don't want to have to fight ddoc because it suddenly decided that some stray bit of syntax which isn't a macro is suddenly significant and does something special. There already complaints for how ddoc does special stuff under some circumstances instead of being purely a question of the macros used: https://issues.dlang.org/show_bug.cgi?id=16068 That particular problem can be solved by using $(COLON), but the more magic syntax there is in ddoc, the more landmines it has. It reminds me of how annoying it is when a piece of software decides that it wants to translate any emojis you type into a graphical image, and it thinks that parts of a piece of code that you type are emojis, so your code gets messed up in the process. Obviously, we're not going to be looking to add emoji support to ddoc, but any magical syntax we add risks similar problems. - Jonathan M Davis
Dec 11 2017
parent reply meppl <mephisto nordhoff-online.de> writes:
On Tuesday, 12 December 2017 at 06:55:45 UTC, Jonathan M Davis 
wrote:
 On Tuesday, December 05, 2017 20:11:33 Walter Bright via 
 Digitalmars-d wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it, 
 but I've
 changed my mind.)
I confess that looking over that page, I don't see much reason to add any of it to ddoc. It all seems like stuff that we can already trivially do in ddoc, and most (all?) of it is stuff that already has built-in macros. What are we really trying to gain here?
1) I avoid writing something like $(I foo) into a comment. Because other people may actually read my source code and not just read a generated documentation from a source code. So, I would prefer writing *foo* or _foo_. After all that's the point of markdown: Pure text _looks_ like intended and enables html-generation at the same time. 2) If someone learns the D programming language, I think it would be advantageous, if that person could just write down the already known markdown grammar
Dec 12 2017
parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Tuesday, December 12, 2017 10:22:24 meppl via Digitalmars-d wrote:
 On Tuesday, 12 December 2017 at 06:55:45 UTC, Jonathan M Davis

 wrote:
 On Tuesday, December 05, 2017 20:11:33 Walter Bright via

 Digitalmars-d wrote:
 https://help.github.com/articles/basic-writing-and-formatting-syntax/

 Anyone interested in picking up the flag?

 (I know this has come up before, and I've been opposed to it,
 but I've
 changed my mind.)
I confess that looking over that page, I don't see much reason to add any of it to ddoc. It all seems like stuff that we can already trivially do in ddoc, and most (all?) of it is stuff that already has built-in macros. What are we really trying to gain here?
1) I avoid writing something like $(I foo) into a comment. Because other people may actually read my source code and not just read a generated documentation from a source code. So, I would prefer writing *foo* or _foo_. After all that's the point of markdown: Pure text _looks_ like intended and enables html-generation at the same time.
And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown. Personally, I would _very_ much like to see the magic formatting in ddoc kept to a minimum. I don't want to have to guess what the documentation is going to look like or have to constantly generate it to make sure that I didn't screw it up because of some stray character that the compiler decided to treat as special. As it stands, ddoc is fairly clean, and it doesn't have a lot of annoying magic - and the stuff that folks frequently find annoying about it tends to be the magic that it does already have - most notably that it decides to invisibly make some words bold based on what's being documented, forcing you to put _ in front of at least some of those words (and most of us have to actually generate the documentation to catch all of the mistakes that have to do with missing underscores; it would be _much_ nicer if that magic weren't there). IMHO, the less magic formatting that ddoc does the better. I want all of that to be controlled by the macros so that you can look at the source code and clearly see all of the formatting commands without them risking looking like something else. - Jonathan M Davis
Dec 12 2017
next sibling parent reply Chris <wendlec tcd.ie> writes:
On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
wrote:
 And then you have to worry about something like int* screwing 
 with things, because the compiler decides that you wanted 
 italics. Honestly, I don't think that something like $(I foo) 
 is very onerous - it's not all that different from <i>foo</i> 
 or [i]foo[/i] (which plenty of folks are familiar with), but 
 it's shorter and less visually noisy - and it doesn't risk 
 having stuff that isn't supposed to be markdown being treated 
 as markdown.

 [...]
Try this one (paste it into http://spec.commonmark.org/dingus/): # CommonMark ``` int* ptr; ``` `int*` is a pointer to an integer. int* is a pointer to an integer.
Dec 12 2017
next sibling parent Chris <wendlec tcd.ie> writes:
On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:

 Try this one (paste it into http://spec.commonmark.org/dingus/):

 # CommonMark

 ```
     int* ptr;
 ```
 `int*` is a pointer to an integer.

 int* is a pointer to an integer.
The output is <h1>CommonMark</h1> <pre><code> int* ptr; </code></pre> <p><code>int*</code> is a pointer to an integer.</p> <p>int* is a pointer to an integer.</p> I don't see any problem here.
Dec 12 2017
prev sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
 On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
 wrote:
 And then you have to worry about something like int* screwing 
 with things, because the compiler decides that you wanted 
 italics. Honestly, I don't think that something like $(I foo) 
 is very onerous - it's not all that different from <i>foo</i> 
 or [i]foo[/i] (which plenty of folks are familiar with), but 
 it's shorter and less visually noisy - and it doesn't risk 
 having stuff that isn't supposed to be markdown being treated 
 as markdown.

 [...]
Try this one (paste it into http://spec.commonmark.org/dingus/): # CommonMark ``` int* ptr; ``` `int*` is a pointer to an integer. int* is a pointer to an integer.
Coming up with a counter example is easy. Try this:
 To dereference a pointer variable, write *i. To define a 
 pointer variable, write int* i.
Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.
Dec 12 2017
next sibling parent meppl <mephisto nordhoff-online.de> writes:
On Tuesday, 12 December 2017 at 13:50:42 UTC, Bastiaan Veelo 
wrote:
 On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
 On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
 wrote:
 And then you have to worry about something like int* screwing 
 with things, because the compiler decides that you wanted 
 italics. Honestly, I don't think that something like $(I foo) 
 is very onerous - it's not all that different from <i>foo</i> 
 or [i]foo[/i] (which plenty of folks are familiar with), but 
 it's shorter and less visually noisy - and it doesn't risk 
 having stuff that isn't supposed to be markdown being treated 
 as markdown.

 [...]
Try this one (paste it into http://spec.commonmark.org/dingus/): # CommonMark ``` int* ptr; ``` `int*` is a pointer to an integer. int* is a pointer to an integer.
Coming up with a counter example is easy. Try this:
 To dereference a pointer variable, write *i. To define a 
 pointer variable, write int* i.
Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.
speaking of "harm". I would say there is not much harm when the API-docs are broken at a certain place. Furthermore it is never super difficult to fix. In comparison: Bugs in a programming language are from a different world and super much more harmful up to 9000.
Dec 12 2017
prev sibling parent Chris <wendlec tcd.ie> writes:
On Tuesday, 12 December 2017 at 13:50:42 UTC, Bastiaan Veelo 
wrote:
 On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
 On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
 wrote:
 And then you have to worry about something like int* screwing 
 with things, because the compiler decides that you wanted 
 italics. Honestly, I don't think that something like $(I foo) 
 is very onerous - it's not all that different from <i>foo</i> 
 or [i]foo[/i] (which plenty of folks are familiar with), but 
 it's shorter and less visually noisy - and it doesn't risk 
 having stuff that isn't supposed to be markdown being treated 
 as markdown.

 [...]
Try this one (paste it into http://spec.commonmark.org/dingus/): # CommonMark ``` int* ptr; ``` `int*` is a pointer to an integer. int* is a pointer to an integer.
Coming up with a counter example is easy. Try this:
 To dereference a pointer variable, write *i. To define a 
 pointer variable, write int* i.
Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.
Like with regex, you can always escape characters with special meanings: To dereference a pointer variable, write \*i. To define a pointer variable, write int* i However, as you said, code would be between back ticks anyway, and even $(I int) can be messed up, if you're not careful with brackets and spaces etc. - which is true of _any_ markup language. By saying "the compiler decides" to do something that wasn't intended after the programmer has not been careful with the syntax, you can dismiss _any_ syntax, including D's. Also, to dismiss CommonMark on the grounds that it is not standardized yet (officially) while millions of programmers are familiar with it an use it on GitHub doesn't make much sense, especially while Ddoc is nowhere near CommonMark in terms of usage, familiarity, ease of use and popularity.
Dec 12 2017
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
wrote:
 Personally, I would _very_ much like to see the magic 
 formatting in ddoc kept to a minimum.
You know what drives me nuts? This* is weird. * it is rendered as a list item! And I know, you can do \*. But ugh. Ugh. Or why is _this_ italic? But those, while enough to bring my hatred, are not why I did something new for adrdox... it is the missed opportunities for links. adrdox links are more inspired by the wikipedia link syntax and uses knowledge of D to keep them very concise: /// Does something. See also: [bar]. void foo(); /// Does something similar. See also: [foo]. void bar(); When it sees a string in brackets, it does a name lookup following D's scoping rules for that declaration, and creates a link to it. It even understands imports (slightly buggy but i'll fix that eventually): import std.stdio; import arsd.color; /// calls [writeln] on the given [Color|color]. void bar(Color s, string txt); You also see the pipe syntax there which replaces the text for the link. It always does [link_to|displayed_text] where displayed_text = link_to if it is not present. In markdown, i often reverse these. But anyway, I struggled a bit on using single brackets for this, since I hate magic syntax too... but I went with it because cross-linking like this is VERY common and adds a lot to the documentation. I use it very frequently (in the docs I've written with the new generator; many of mine are still in the transition period from ddoc). In fact, I use it almost as frequently as `code` (which doesn't attempt namespace lookups because it is too generic and linking in there leads to silly results). Phobos' $(REF) macro tries to do something similar but it is a huge pain since it needs more qualification; it doesn't look stuff up in the actual D. Cross linking in documentation I find is a huge win in legibility for the coder and readability for the end user. *this* vs $(B this)? meh whatever.
Dec 12 2017
next sibling parent Biotronic <simen.kjaras gmail.com> writes:
On Tuesday, 12 December 2017 at 16:12:50 UTC, Adam D. Ruppe wrote:
 Ugh. Or why is _this_ italic?
I know! /This should be italic./ _This should be underlined._ How anyone could manage to mess those up is way beyond me. Some digging indicates it's a decision based on the fact that both are used for emphasis. This goes in the same drawer as '9 = 3, because they're both numbers'. Of course, since underlined text is generally not a good idea, the solution to that specific problem is to simply not support underscores for emphasis. This leaves us with /italics/ being indicated by *asterisks*, which I find acceptable. -- Biotronic
Dec 12 2017
prev sibling parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Tuesday, December 12, 2017 16:12:50 Adam D. Ruppe via Digitalmars-d 
wrote:
 On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis

 wrote:
 Personally, I would _very_ much like to see the magic
 formatting in ddoc kept to a minimum.
You know what drives me nuts? This* is weird. * it is rendered as a list item! And I know, you can do \*. But ugh. Ugh. Or why is _this_ italic? But those, while enough to bring my hatred, are not why I did something new for adrdox... it is the missed opportunities for links. adrdox links are more inspired by the wikipedia link syntax and uses knowledge of D to keep them very concise: /// Does something. See also: [bar]. void foo(); /// Does something similar. See also: [foo]. void bar(); When it sees a string in brackets, it does a name lookup following D's scoping rules for that declaration, and creates a link to it. It even understands imports (slightly buggy but i'll fix that eventually): import std.stdio; import arsd.color; /// calls [writeln] on the given [Color|color]. void bar(Color s, string txt); You also see the pipe syntax there which replaces the text for the link. It always does [link_to|displayed_text] where displayed_text = link_to if it is not present. In markdown, i often reverse these. But anyway, I struggled a bit on using single brackets for this, since I hate magic syntax too... but I went with it because cross-linking like this is VERY common and adds a lot to the documentation. I use it very frequently (in the docs I've written with the new generator; many of mine are still in the transition period from ddoc). In fact, I use it almost as frequently as `code` (which doesn't attempt namespace lookups because it is too generic and linking in there leads to silly results). Phobos' $(REF) macro tries to do something similar but it is a huge pain since it needs more qualification; it doesn't look stuff up in the actual D. Cross linking in documentation I find is a huge win in legibility for the coder and readability for the end user. *this* vs $(B this)? meh whatever.
Yeah. Unfortunately, given that ddoc is designed to be only a macro language and tries to not focus on html generation specifically, I don't know how feasible it is to make it deal with links properly while still working with other target formats. On some level ddoc's flexibility undermines it as a good tool for generating documentation. But for most of us, if ddoc could be improved to actually generate cross-links by default where appropriate (e.g. parameter types to the documentation for those types) and have built-in macros for manually generating cross-links within the documentation, then that would be a huge step up. As it stands, I think that in most cases, using something like ddox or adrdox works a lot better than using ddoc for everything, which is kind of sad given that the whole point of ddoc was to have something built-in for easily generating documentation. Maybe at some point, I'll look at seeing how reasonable it is to improve ddoc to deal with the links properly, but I'm not very familiar with the compiler, and I have too many projects as it is. - Jonathan M Davis
Dec 12 2017