Cross referencing in Ddoc

[Sönke Ludwig]

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.