www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc with cross-references

reply Ary Manzana <ary esperanto.org.ar> writes:
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...
Apr 01 2012
next sibling parent Ary Manzana <ary esperanto.org.ar> writes:
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...
Apr 01 2012
prev sibling next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Apr 01 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
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.
Apr 01 2012
next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
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...
Apr 01 2012
parent Ary Manzana <ary esperanto.org.ar> writes:
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
Apr 01 2012
prev sibling parent Jacob Carlborg <doob me.com> writes:
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
Apr 01 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Apr 01 2012
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
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
Apr 01 2012
prev sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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.)
Apr 02 2012