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