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.

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

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.

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

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

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.

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.