Ddoc as general documentation tool (was Re: DDoc and logically structured HTML)

[Andrei Alexandrescu]

On 3/19/12 5:01 AM, Gour wrote:
> On Sun, 11 Mar 2012 01:08:20 +0000
> Stewart Gordon<smjg_1998 at yahoo.com>  wrote:
>
>> Has anybody else got further with getting logical HTML out of DDoc?
>> Have you been using DDoc to generate some internal format and then
>> some other program to turn it into HTML, or what?
>
> Excuse me for jumping into the thread, but I hope it's relevant...
>
> I wonder whether you can recommend using Ddoc for writing
> general-purpose documentation like user's manual for e.g. application
> written in D which has to be split into logical parts (chapters,
> sections,...) as well as use hyperlinking, addding pictures, tables
> etc.?
>
> Or do you believe it's better to use more specialized tool like reST
> markup with Sphinx, AsciiDoc, LaTeX/LyX...?
>
> Let me add that we'd like to have nice HTML output which can be invoked
> within application itself as well as quaility output in the form of PDF
> file.

DDoc has two main assets: (a) it understands D structures, e.g. you can 
use it to document D APIs, and (b) it highlights D code nicely.

Aside from that, it's a fairly simple macro system. If you don't have a 
need for (a)/(b), it is a passable document generation tool (pretty much 
as e.g. m4 would be). We use it for D's own website, and it's okay in 
helping with HTML generation.

More specialized tools that have a focus on document formatting have 
naturally an advantage over DDoc for general-purpose documentation.


Andrei