DDoc with cross-references

[Ary Manzana]

On 4/2/12 2:07 PM, Jonathan M Davis wrote:
> On Monday, April 02, 2012 13:52:47 Ary Manzana wrote:
>> On 4/2/12 12:39 PM, Jonathan M Davis wrote:
>>> On Monday, April 02, 2012 12:20:31 Ary Manzana wrote:
>>>> I'm planning to add cross-references to the default ddoc output. At
>>>> least that's the simplest thing I could do right now that might improve
>>>> ddoc somehow.
>>>>
>>>> I see the documentation generated for phobos, for example:
>>>>
>>>> http://dlang.org/phobos/std_array.html#Appender
>>>>
>>>> has anchors to the many symbols (in fact, now I notice it's flawed,
>>>> because they are not fully-qualified).
>>>>
>>>> Does anyone know where can I get the macros for generating such output?
>>>> I will need it for generating the cross-links.
>>>>
>>>> But a more appropriate question is: why the default ddoc output doesn't
>>>> generate such anchors by default? At least putting an ID to the
>>>> generated DT...
>>>
>>> Phobos' macros are in
>>>
>>> https://github.com/D-Programming-Language/d-programming-
>>> language.org/blob/master/std.ddoc
>>>
>>> As for linking macros,
>>>
>>> LREF is used for references within a module.
>>> XREF is used for references to std modules.
>>> CXREF is used for references to core modules.
>>> ECXREF is used for references to etc.c modules.
>>
>> Again, the same things. D has ddoc and it tries to do everything with
>> ddoc. No, that's plain wrong. Links to other module members should be
>> done automatically. And the links should come from the compiler. The
>> compiler has that knowledge already, why loose it and work on a less
>> powerful level (ddoc)?
>
> I'm not arguing it one way or another. I'm just pointing out how it works now.
>
>>> As for Appender, I don't see any links at all, so I don't know what you're
>>> talking about. The generic D macro (which just designates D code) is used
>>> by it in some places, and ddoc does put some stuff in italics in some
>>> cases (e.g. the name of a function's parameter in the documentation for
>>> that function), but there are no links in Appender's documentation.
>>
>> What I meant is, every member in the module has an anchor. In the case
>> of Appender it looks like this in the generated HTML:
>>
>> <a name="Appender"></a>
>>
>> That's why I can give you this link:
>>
>> http://dlang.org/phobos/std_array.html#Appender
>>
>> and it scrolls down to Appender (I know you know it already, but it
>> seems I wasn't clear in my previous post).
>>
>> Now, that is flawed because the name is not fully qualified. And there's
>> no macro to get a fully qualified name or link to other members modules.
>
> The anchors have been a big problem for a long time. A prime example of where
> they're horrible is std.datetime. They maintain _no_ hierarchy whatsoever. So,
> _everything_ gets lumped together as it were a free function, and if anything
> has the same name (e.g. DateTime and SysTime both have a year property), then
> they end up with identical anchors. The result is that the links at the top of
> std.datetime are nearly useless.
>
> It's ddoc's biggest problem IMHO.

Thanks again. This is what I want to fix.

I see this in the source code:

DDOC_DECL      = $(DT $(BIG $0))\n\

So what I want to do is to change that so that it includes an anchor. 
Should I change it to:

DDOC_DECL      = $(DT <a name="$0" /> $(BIG $1))\n\

or something like that, and then pass two arguments?

I find it hard to change the documentation output while having to deal 
with all those macros...