Single Source Documentation Tool

Question

What OSS (or free) tools are available for compiling a single source of documentation that can be used to create manuals? In particular, in the following formats:

• HTML site
• PDF document
• Embeddable (inside the application, possibly HTML) ¹
• Text (optional)
• Personal pages (optional)

Additional requirements:

• The tool is suitable for technical authors (not necessarily WYSIWYG).
• XML / SGML Source
• High-quality PDF output (comparable to TeX)
• Multi-platform

Extended requirement ¹

The same command line application is written in two languages ​​(C and Java). Using XML to describe command-line options (some of which refer to only one language or another), it is easy to convert XML to a Java class or C function, which writes reference information on standard outputs. This ensures that help can be embedded in the binary, regardless of external files.

AsciiDoc does not seem to have this ability. Is there any other option?

Answer 1

The one that satisfies most of your requirements that I used earlier is AsciiDoc .

AsciiDoc is not XML source code, but instead selects a plain text format. It can output HTML and Docbook, which can be presented in PDF or other formats. The source text is good enough for a simple text presentation.

Another popular choice in the same vein is reStructuredText .

Answer 2

I see DocBook evangelism as a replacement for Word in our engineering team. There are many toolkits available. The easiest for engineers is probably DocBook XSL , Apache FOP , and Ant or Make . Here's how I made my DocBook stuff. If you really are logging into LaTeX, you can check out DBLaTeX for the DocBook to LaTeX publishing environment.

If you don't mind going beyond the free environment, then the <oXygen/> XML Editor offers a pretty good WYSIWYG DocBook editor. I haven't used it that much, but it looks pretty promising.

Answer 3

Doxygen is a documentation generator that is quite popular and can output documents in various formats . Although its main purpose is to create documentation extracted from the original comments (from several languages), it is also quite applicable as a regular tool for writing a guide. In fact, the Doxygen website and guide are created this way.

Answer 4

Sphinx is a tool that adds a number of Docutils features, allowing you to write “smart and beautiful documentation” in reStructuredText. It was originally created to create new Python documentation, but has been accepted by many other projects.