On Thu, Jul 10, 2014 at 05:52:57PM -0400, Nick Sabalausky via Digitalmars-d wrote: > On 7/10/2014 4:01 AM, Jacob Carlborg wrote: [...] > >Is it only me that feels like ddoc doesn't scale for designing web > >sites. > > > > Not just you, I've been kind of avoiding it. I like that it *exists* > as a built-in, and it's certainly better than those XML "comments" > that C# uses, but it still has poor readability (and writeability) > *within* the source, plus it's really just too "dumb": Purely > zero-semantics macro-like text substitution just isn't good enough. > Realistically, you just end up needing to post-process its results if > you don't want to feel like you've got your hands tied behind your > back. In which case, why even bother using it at all? > > I've always wanted something in D that's more like Natural Docs: > http://www.naturaldocs.org/documenting.html > > Macroed comments are just an overengineered mess compared to that.
Hmm. In terms of input syntax, I quite like Natural Docs. But it only supports HTML output currently. :-( While ddoc as a macro system is quite nice, for documentation generation I personally prefer something that understands the semantics of the documentation better. The current way of generating indices and cheat sheets at the top of Phobos module docs, for example, is extremely ugly because it's manual. Ideally, a doc generator system should automate these sorts of things by allowing, say, a generic $(tableofcontents) directive that does the Right Thing(tm). It also should support moving things around (e.g., sort function docs by name, split them up into separate pages, etc.), without requiring external postprocessing tools to achieve. At the end of the day, the ideal seems to be something akin to Knuth's literate programming: you work on a single source, and the codegen extracts the code parts of it and feeds it to the compiler (possibly reordering pieces of the code), and the docgen extracts the doc parts of it (possibly moving them around) and assembles them into a nicely-formatted document. Retaining semantic information on the docs is important, since the docgen may need to consult this info to make decisions about where to put things -- currently ddoc is incapable of this and thus can only generate docs in source order. Retaining semantic structure also allows clean multiplexing into different output formats. While ddoc does allow this to a limited extent, it requires a lot of manual intervention (introduce intermediate layers of macros to serve as abstractions over different output formats) and unnatural ways of writing the input. As a simple example, in LaTeX "Mr. Doe" should be written as "Mr.\ Doe" to get the correct spacing, but in HTML it's "Mr. Doe". You'd have to write "Mr.$(NBSP)Doe" in order to target both HTML and LaTeX, which makes the source quite unreadable. T -- It always amuses me that Windows has a Safe Mode during bootup. Does that mean that Windows is normally unsafe?
