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.
