Cross referencing in Ddoc

[Andrei Alexandrescu]

On 1/1/14 4:56 AM, Jacob Carlborg wrote:
> On 2013-12-31 18:08, Andrei Alexandrescu wrote:
>
>> That's an exaggeration. The top of std.algorithm produces complex output
>> (two tables). The rest of the documentation is nice and legible.
>
> std.algorithm contains 335 lines of ddoc comments. I would consider that
> "hundreds", or does "hundreds" mean something else.

I replied to "Hundreds of lines of Ddoc madness" with "that's an 
exaggeration". Do you really think I was refuting the factual 335 lines?

> What I'm saying is
> that those two tables should be automatically generated, at least the
> first one.

Yah, that would be nice.

>> As one who's written both, I can testify this isn't true. Ddoc macros
>> need to be mentioned once and then the closing paren completes them.
>> Additionally, they can expand to arbitrarily complex output. In
>> contrast, tags need to be mentioned twice (an often-mentioned issue with
>> writing HTML by hand), are syntactically heavier, and therefore litter
>> the text a lot more.
>
> I'm considering it to be a sort of tag, just with a different syntax.
> Who said tags need to have an end tag. A less verbose a minimal reliance
> on tags would be Markdown or similar. Creating a list in Markdown is
> simple as:
>
> * this
> * is
> * a
> * list
> * in Markdown

I prefer ddoc to markdown for its flexibility. Ddoc is an almost pure 
macro expansion system with minimal syntax. Markdown defines a bunch of 
syntax but has (last time I looked) is weak on macro capability.

Case in point: markdown lists will be styled one way. With DDoc macros 
one can define any style of lists needed. (We've defined BOOKTABLE in 
addition to a couple of other TABLEs, which works beautifully in HTML 
and LaTeX; not sure how can be done in Markdown.

> If there's a specific macro that would indicate a category then it would
> be easy to generate a table like that.
>
> /// $(CATEGORY searching)
> void foo ()

The issue is with writing text out of order, something DDoc is not very 
apt at. Would be nice to improve on that (we do some of it with javascript).


Andrei