Cross referencing in Ddoc

[Andrei Alexandrescu]

On 12/31/13 4:26 AM, Jacob Carlborg wrote:
> On 2013-12-31 01:05, Sönke Ludwig wrote:
>
>> Also, the official first four goals of DDOC are:
>>
>>> 1. It looks good as embedded documentation, not just after it is
>>>     extracted and processed.
>
> It certainly does not. Just have a look at the top of std.algorithm or
> std.uni. Hundreds of lines of Ddoc madness.

That's an exaggeration. The top of std.algorithm produces complex output 
(two tables). The rest of the documentation is nice and legible.

>>> 2. It's easy and natural to write, i.e. minimal reliance on <tags> and
>>>     other clumsy forms one would never see in a finished document.
>
> Fails again. As soon as you need something more advanced than the
> standard sections you need to use macros. The macros are just as tags,
> just with a different syntax and name.

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.

>>> 3. It does not repeat information that the compiler already knows from
>>>     parsing the code.
>
> You sure need to do if you want good documentation. Take a look at
> std.algorithm, it has over 300 lines of Ddoc code to create a symbol
> table that Ddoc should be able to automatically generate.

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.

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.

>>> 4. It doesn't rely on embedded HTML, as such will impede extraction
>>>     and formatting for other purposes.
>
> As far as I know this isn't very useful. For the other formats we use,
> like PDF, it uses the HTML output as a base.

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


Andrei