Cross referencing in Ddoc

[Jacob Carlborg]

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. What I'm saying is 
that those two tables should be automatically generated, at least the 
first one.

> 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

> No. There are two tables there. One is a categorization of algorithms,
> which is human-made. There are several solutions to materializing that
> table but they all would require the intervention of a human being. I
> figured std.algorithm adds new algorithms rarely enough to allow myself
> a solution that requires manual intervention.

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 second table is a "cheat sheet" with human-produced short
> descriptions for each function. Those short descriptions wouldn't fit
> well with the longer descriptions.

That can also be generated automatically. Ddoc can just insert the 
summary [1] for each symbol.

[1] The Ddoc documentation says:

"The first section is the Summary, and does not have a section name. It 
is first paragraph, up to a blank line or a section name. While the 
summary can be any length, try to keep it to one line."

http://dlang.org/ddoc.html

> Again no. You are misinformed. The PDF manual is generated via LaTeX
> from the same ddoc sources as the HTML pages.

Ok, fair enough.

-- 
/Jacob Carlborg