On 12/10/2011 9:52 PM, Adam D. Ruppe wrote:
Jonathan M Davis Wrote:
In fact, as much of the documentation-
generation as possible should be in ddoc IMHO. That way, anyone can get
reasonable documentation for their own projects.
I agree to an extent, but at the same time, I like keeping ddoc itself fairly
simple.
Correct anchors from ddoc are a no-brainer, it definitely should be doing that.
I'd also like for it to mark off any D names it sees, so we can link them right
into
a search engine or something to do automatic cross referencing. (I want to add
this to my program too, but regardless, the compiler would do a much better job
at it than a regular expression or whatever I can do with the text.)
I'm still meaning to revamp the compiler's default set of macros too, when I
get around to it.
But, I'm mixed on things like tables of contents. On one hand, it's definitely
a useful thing to have, but on the other, how much can ddoc do without
getting a lot more complicated?
I'd hate to add a bunch of special cases in there, or worse yet, a whole bloody
scripting language, to cover everyone's use-case. If we do tables, what's next?
Though a nice content listing probably *is* worth it...
Keeping ddoc simple and running the generated document through an additional
program gives you all the flexibility of D - or whatever - without adding to the
compiler.
If you take a look at my program: http://arsdnet.net/d-web-site/improveddoc.d
you can see that it isn't terribly complex, but part of that is that it uses my
html dom library and std.algorithm to help out; of we replicated that inside
the compiler it might be a lot messier.
Actually it might be nice instead of ddoc creating HTML if it created an
intermediate XML or JSON format of documentation that could be
transformed via XSLT+CSS into the final product be it html, chm,
manpages etc.
