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