Single source documentation tool

Question

What OSS (or free) tools are available for drafting a single source for documentation that can be used to generate manuals? Specifically, in the following formats:

• HTML website
• PDF document
• Embedded (within an application; possibly HTML)¹
• Text (optional)
• Man pages (optional)

Additional requirements:

• Tool is suitable for technical writers (need not be WYSIWYG).
• XML/SGML source
• High quality PDF output (comparable to TeX)
• Multi-platform

Expanded Requirement¹

The same command-line application is written in two languages (C and Java). Using XML to describe the command-line options (some of which are specific to one language or the other), it is straightforward to transform the XML into a Java class, or a C function, which writes help to standard output. This ensures that the help can be embedded into the binary without having to depend on external files.

It appears AsciiDoc does not have this ability. Is there another option?

Answer 1

One that satisfies most of your requirements, that I've used before, is AsciiDoc.

AsciiDoc isn't an XML source format though, instead it opts for a simple text format. It can output HTML and Docbook, which can be rendered into PDF or other formats. The source text is nearly good enough for plain text presentation, too.

Another popular choice along the same lines is reStructuredText.

Answer 2

I've been considering evangelizing DocBook as a replacement for Word in our engineering group. There are a number of toolchains available. The easiest for engineers is probably DocBook XSL, Apache FOP, and either Ant or Make. This is how I have been doing my DocBook stuff. If you are really into LaTeX, then you might want to check out DBLaTeX for a DocBook to LaTeX publishing environment.

If you don't mind stepping outside of the free environments, then the <oXygen/> XML Editor offers a pretty nice WYSIWYG DocBook editor. I haven't used it that much, but it does look pretty promising.

Answer 3

Sphinx is a tool that adds a number of features to Docutils, allowing "intelligent and beautiful documentation" to be written in reStructuredText. It was originally created to produce the new Python documentation but is being adopted by many other projects.

Answer 4

Doxygen is documentation generator that's quite popular and can output documents in a variety of formats. Although its primary purpose to build documentation extracted from source comments (from numerous languages), it's also quite usable as a general manual writing tool. In fact, the Doxygen website and manual are generated in this way.