Search code examples
javapdf-generationdocumentation-generation

Single source documentation tool


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)1
  • 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 Requirement1

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?


Solution

  • 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.