Ruff! Output Formatters

Ruff! can either directly generate HTML documentation using the built-in HTML formatter, or generate formats that can be understood by several existing tools such as  ROBODoc, Natural Docs or doctools.

Each option has its advantages and disadvantages.

The internal HTML formatter offers (in the author's humble opinion) the best cross-linking and navigation support in addition to cosmetic enhancements such as tooltips and optional hiding/display of source code. It is also the simplest to use as no other external tools are required.

The external formatters have the advantage of supporting many more output formats such as PDF, plain text, Latex etc. In additional the generated documentation can be integrated into other larger documentation sets that contain documentation from other sources.

Choice of an output formatter depends on several factors:

• the end use document format desired - ROBODoc and doctools support several output formats but the Ruff! internal formatter and Natural Docs support only HTML;
• existing familiarity with a tool - obviously, if you are already familiar with a tool, or want to integrate Ruff! output with other documentation, it makes sense to stick with a tool you know;
• capabilities of the tool itself - some tools are better than others in some areas such as quality of output generated, automatic cross-linking and indexing, configurability etc.

In my biased opinion, Ruff! built-in HTML formatter and Natural Docs to be the best (in that order) if you want HTML output. From a purely formatting perspective, doctools is the most capable, and works at the semantic level unlike other external formatters. Its HTML output is decent and it supports many other formats as well. The biggest drawback in my mind is that its cross-linking is very limited. ROBODoc's strength would appear to be its support for additional formats like XML DocBook which can be used to generate even more output formats like Microsoft Help.

In general, it is best to try all formatters and pick one that best meets your needs.