Cross referencing in Ddoc

Andrei Alexandrescu SeeWebsiteForEmail at erdani.org
Tue Dec 31 10:16:38 PST 2013


On 12/31/13 9:39 AM, Sönke Ludwig wrote:
> Am 31.12.2013 17:48, schrieb Andrei Alexandrescu:
>> 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.

I see #identifier.chain similar to e.g. $(X identifier.chain) so no 
issue with that. It just adds more syntax without necessity. I'd instead 
work on improving macros to generate proper xrefs out of $(X ...) rather 
than adding new syntax. But either way is fine.

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

Agreed. In all likelihood I misunderstood something because I thought 
you were referring to cross-referencing text without any user intervention.


Andrei



More information about the Digitalmars-d mailing list