Cross referencing in Ddoc

[Marco Leise]

Am Tue, 31 Dec 2013 10:28:46 +0100
schrieb Sönke Ludwig <sludwig at outerproduct.org>:

> Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
> > On 12/30/13 1:00 PM, Walter Bright wrote:
> >> On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
> >>> Oh the default is to link and then disable manually? That's still
> >>> manual, just
> >>> the default is different :o). I can work with that.
> >>
> >> As I mentioned elsewhere, I dislike the requirement to use the inverse
> >> feature. Consider maintenance - I add a symbol, and then have to grep
> >> the rest of the module for any inadvertent collisions? Features should
> >> be positive ones, not negative.
> > 
> > Your arguments are convincing.
> > 
> > Andrei
> > 
> 
> The argument in isolation is sound, no doubt. But alone it doesn't lead
> to a solution*. There are a lot of arguments regarding the current
> situation and if the decision is not to use the existing _negative rule,
> then all of those should be carefully taken into account.
> 
>  - Visual noise and effort when using $(XREF) style macros
>  - $(XREF) isn't sufficient! A multitude of macros is actually needed
>  - There is no standard set of macros, it's project specific
>  -> The whole documentation needs to be revised when moving code between
>     projects!
>  - Macros need to be carefully crafted so that they don't encode
>    knowledge about the final documentation/file structure
>  - Macros alone can't cope with nested directory structures
>  - The cognitive load for multiple such macros would very likely cause
>    them to go unused in many cases
> 
> My favorite solution would be to introduce a simple #identifier.chain or
> @identifier.chain syntax to let the compiler or documentation generator
> insert the proper links or macro calls. Using a sepecial $(REF
> identifier.chain) pseudo macro, like Jacob suggested, would work as
> well, but I can't see how the additional syntax/visual/typing overhead
> is justified for such a common feature - at least when trying to find an
> optimal solution, compared to the current macro based system it would of
> course still be a big improvement.
> 
> But still, considering that there is precedence for the _negative
> approach (i.e. the problems of it are already there), I find using that
> acceptable, too, even if the concept is not as pretty/clean.
> 
> 
> * *Some* solution is needed. The different structure of the DDOX
> documentation for example makes the $(XREF) macros worthless, so they
> are currently completely disabled and automatic link generation is used
> instead.

I'm fully with you on that one and I would like to add that
DDoc's macro system reverses the responsibilities. Instead of
writing easy to read documentation that is agnostic to the
target output, you have to take into account any potential
output format's peculiarities.
This starts with the list of escaped characters in your
custom template and ends with structuring elements for lists
and tables. Without abstraction of structuring elements in
DDoc lists and tables look like HTML and are likely not
portable to other formats that use a different or implicit
structuring scheme. E.g. if you wanted to support MarkDown with
its explicit numbers for ordered lists, you'd have to replace
all $(LI) with $(LI1), $(LI2), ...
I guess it is a little too late to ask for a complete
reimplementation of DDoc?

-- 
Marco