The testing of the process of converting from DocBook to man pages, or Texinfo, is complicated by the fact that a given input (the DocBook document) usually does not have one specific, well-defined output. Variations on the output are allowed for the result to look “nice”.
When docbook2X was in the early stages of development, the author tested it simply by running some sample DocBook documents through it, and visually inspecting the output.
Clearly, this procedure is not scaleable for testing a large
number of documents. In the later 0.8.x versions of docbook2X, the
testing has been automated as much as possible.
The testing is implemented by heuristic checks on the output to see if it comprises a “good” man page or Texinfo file. These are the checks in particular:
Validation of the Man-XML or Texi-XML output, from the first stage, XSLT stylesheets, against the XML DTDs defining the formats.
Running groff and makeinfo on the output, and noting any errors or warnings from those programs.
Other heuristic checks on the output, implemented by a Perl script. Here, spurious blank lines, uncollapsed whitespace in the output that would cause a bad display are checked.
There are about 8000 test documents, mostly refentry documents, that can be run
against the current version of docbook2X. A few of them have been
gathered by the author from various sources and test cases from bug
reports. The majority come from using doclifter
on existing man pages. Most pages pass the above tests.
To run the tests, go to the test/
directory in the docbook2X distribution. The command make check will run some tests on
a few documents.
For testing using doclifter, first generate the DocBook XML
sources using doclifter, then take a look at the test/mass/test.pl testing script and run it. Note
that a small portion of the doclifter pages will fail the tests,
because they do not satisfy the heuristic tests (but are otherwise
correct), or, more commonly, the source coming from the doclifter
heuristic up-conversion has errors.