Cross referencing in Ddoc

[Andrei Alexandrescu]

On 12/31/13 1:28 AM, Sönke Ludwig wrote:
> 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

In a nutshell, "good cross-referencing is hard". That's exactly the 
experience of anyone who's created an index. In publishing there are 
automatic index generators and they're universally known to be vastly 
inferior to professional-produced ones. I've created my own index by 
hand for TDPL and it's been difficult, but probably the result is better 
than an automated index.

Andrei