Documentation generation

[retard]

Sun, 08 Aug 2010 02:22:30 +0000, dsimcha wrote:

> == Quote from Bernard Helyer (b.helyer at gmail.com)'s article
>> I'm writing a compiler, not a half-arsed documentation generator
>> (because if I wrote the DDoc stuff, that's exactly what it would be).
> 
> I'll concur with Walter.  I think that sometimes power users of a given
> tool/feature fail to realize that very often simple, good enough and
> works out of the box beats well-designed, feature-packed, efficient, but
> a PITA to set up and use, overkill for simple cases, and not available
> out of the box.  I understand treating ddoc as a low priority feature,
> but **please** support it eventually, as the whole point of it is that
> it's just there on any implementation (nothing separate to
> download/configure) and just works for the simplest 80-90% of cases even
> if its deficiencies become obvious in the last 10-20%.
> 
> In general I also think that DDoc's evolution is actually good design
> strategy.  I wish more tools were designed by pinning down how the
> simplest 80-90% of cases should work first, treating that as a
> constraint and then figuring out how to make the most complicated 10-20%
> work within the constraint.  Designing with "everything must be
> possible" as the first goal encourages overengineering such that users
> with simple needs end up reinventing the wheel because it's the path of
> least resistance.  For example, I'd probably never use Ddoc if I had to
> use XML for it.

The problem with ddoc is that even though 1000+ documentation formats 
already existed, he wanted to reinvent his own. The ddoc syntax is 
terrible ad-hoc crap and geared towards html (3.2/4). Has anyone 
seriously tried to generate any non-html documents with ddoc which look 
as good as better than those created with e.g. doxygen?! I've personally 
just filtered out the bad constructs from the sources and rendered with 
the buggy doxygen. Much better. I get nice pdf/tex/man/xml output.