Cross referencing in Ddoc

[Sönke Ludwig]

Am 31.12.2013 17:48, schrieb 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".

I don't think so at all (on the technical level). What is the issue with 
using the #identifier.chain pattern for example? It seems simple enough 
and I can't imagine a more natural thing than to reference symbols in 
documentation the same way as in code.

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

But index generation is a higher level issue. The basis for it is to 
have some kind of universal anchor that can be used as a reference. 
#identifier.chain or $(REF identifier.chain) is nothing more than that 
and just solves the issue of supporting arbitrary nested scopes and 
different file system or document hierarchies.