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
==========

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/):



```
     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/):



 ```
     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/):



 ```
     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/):



 ```
     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/):



 ```
     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