<?xml version="1.0" encoding="utf-8" ?>
<sect1 id="testing">
<sect1info>
<abstract role="texinfo-node">
  <para>Discussion of correctness-testing</para>
</abstract>
</sect1info>

<title>How docbook2X is tested</title>

<indexterm><primary>testing</primary></indexterm>
<indexterm><primary>correctness</primary></indexterm>
<indexterm><primary>validation</primary></indexterm>

<para>
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”.
</para>

<para>
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.
</para>

<para>
Clearly, this procedure is not scaleable for testing
a large number of documents.
In the later 0.8.<replaceable>x</replaceable> versions
of docbook2X, the testing has been automated
as much as possible.
</para>

<para>
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:
</para>

<orderedlist>

  <listitem>
    <para>
      Validation of the Man-XML or Texi-XML output,
      from the first stage, XSLT stylesheets,
      against the XML DTDs defining the formats.
    </para>
  </listitem>

  <listitem>
    <para>
      Running &groff_ref; and &makeinfo_ref;
      on the output, and noting any errors
      or warnings from those programs.
    </para>
  </listitem>

  <listitem>
    <para>
      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.
    </para>
  </listitem>
</orderedlist>

<para>
There are about 8000 test documents,
mostly <sgmltag class="element">refentry</sgmltag>
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 
<ulink url="http://www.catb.org/~esr/doclifter/">doclifter</ulink>
on existing man pages.
Most pages pass the above tests.
</para>

<para>
To run the tests, go to the <filename>test/</filename>
directory in the docbook2X distribution.
The command <userinput>make check</userinput> will run
some tests on a few documents.
</para>

<para>
For testing using doclifter,
first generate the DocBook XML sources using doclifter,
then take a look at the <filename>test/mass/test.pl</filename>
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.
</para>
      
</sect1>