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

On 4/2/12 12:20 PM, 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...

I also wonder why it's not implemented. I mean, it seems *so* easy to do it. Just add a toDdocChars() method to every Dsymbol. For basic types, just output their string representation (int, float, etc.). For classes, structs, etc, just output:

<a href="module_name.html#struct_name">struct_name</a>

or something like that...

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.

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.

- Jonathan M Davis

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)?

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

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.

- Jonathan M Davis

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

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

On 2012-04-02 06:20, 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.

That would be so nice to have.

-- 
/Jacob Carlborg

On 2012-04-02 07:52, Ary Manzana wrote:
> On 4/2/12 12:39 PM, Jonathan M Davis wrote:
>> 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)?

In general I think the compiler should automatically output cross-references. But there are cases when you want to manually refer to other parts of the documentation and in these cases you would needed these macros.

-- 
/Jacob Carlborg

On Monday, 2 April 2012 at 04:20:16 UTC, Ary Manzana wrote:
> (in fact, now I notice it's flawed, because they are not fully-qualified).

I have a dmd pull request waiting for a few fixes from me
that will help with this.

It adds fully qualified names to one of the outputs so we
can do anchors from it, and also fixes the godawful mess
that is proper character encoding right now (by doing custom
character replacement prior to macros. This disables the
embedded HTML misfeature, which breaks a lot of the website
right now, but is a big win for sanity.)