Cross referencing in Ddoc

[Jacob Carlborg]

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.

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

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

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

To me it looks like it failed on all four of these goals.

> Using $(XREF), $(TABLE $(TR $(TD ...))), $(LINK a b) $(D ...) and so on
> is nothing but markup. If we go that route, we could as well remove all
> syntax, except for the macros:
>
> $(SUMMARY ...)
> $(SECTION See_Also
>     ...
> )
> $(PARAMS
>    $(PARAM x ...)
>    $(PARAM y ...)
> )
> $(SECTION Example
>    $(CODEBLOCK
>      ...
>    )
> )
>
> But you added the syntax for a reason back then (readability ...and
> writability). And the same goes for the auto-detection of identifiers. I
> think the only problem is that the default would have been better off
> the other way around.
>

I completely agree.

-- 
/Jacob Carlborg