d-programming-language.com

[Hans Uhlig]

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.