DDoc with cross-references

[Ary Manzana]

On 4/2/12 2:16 PM, Ary Manzana wrote:
> 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...

Nevermind, found how to do it. I hope I can make it soon, hehe... :-P