Cool Stuff for D that we keep Secret

[H. S. Teoh via Digitalmars-d]

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?