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