<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<title>docbook2X: How docbook2X is tested</title>
<link rel="stylesheet" href="docbook2X.css" type="text/css" />
<link rev="made" href="mailto:stevecheng@users.sourceforge.net" />
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
<meta name="description" content=
"Discussion of correctness-testing" />
<link rel="start" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="up" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="prev" href="performance.html" title=
"docbook2X: Performance analysis" />
<link rel="next" href="todo.html" title="docbook2X: To-do list" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">How docbook2X is tested</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href=
"performance.html"><< Previous</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href=
"todo.html">Next >></a></td>
</tr>
</table>
<hr /></div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="testing" name="testing"></a>How docbook2X
is tested</h2>
</div>
</div>
</div>
<a id="id2540807" class="indexterm" name="id2540807"></a><a id=
"id2540814" class="indexterm" name="id2540814"></a><a id=
"id2540820" class="indexterm" name="id2540820"></a>
<p>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”.</p>
<p>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.</p>
<p>Clearly, this procedure is not scaleable for testing a large
number of documents. In the later 0.8.<em class=
"replaceable"><code>x</code></em> versions of docbook2X, the
testing has been automated as much as possible.</p>
<p>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:</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>Validation of the Man-XML or Texi-XML output, from the first
stage, XSLT stylesheets, against the XML DTDs defining the
formats.</p>
</li>
<li>
<p>Running <span class="citerefentry"><span class=
"refentrytitle"><span><strong class=
"command">groff</strong></span></span></span> and <span class=
"citerefentry"><span class="refentrytitle"><span><strong class=
"command">makeinfo</strong></span></span></span> on the output, and
noting any errors or warnings from those programs.</p>
</li>
<li>
<p>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.</p>
</li>
</ol>
</div>
<p>There are about 8000 test documents, mostly <code class=
"sgmltag-element">refentry</code> 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 <a href=
"http://www.catb.org/~esr/doclifter/" target="_top">doclifter</a>
on existing man pages. Most pages pass the above tests.</p>
<p>To run the tests, go to the <code class="filename">test/</code>
directory in the docbook2X distribution. The command <strong class=
"userinput"><code>make check</code></strong> will run some tests on
a few documents.</p>
<p>For testing using doclifter, first generate the DocBook XML
sources using doclifter, then take a look at the <code class=
"filename">test/mass/test.pl</code> 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.</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href=
"performance.html"><< Previous</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href=
"todo.html">Next >></a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Performance
analysis </td>
<td width="20%" align="center"><a accesskey="h" href=
"docbook2X.html">Table of Contents</a></td>
<td width="40%" align="right" valign="top"> To-do list</td>
</tr>
</table>
</div>
<p class="footer-homepage"><a href=
"http://docbook2x.sourceforge.net/" title=
"docbook2X: Home page">docbook2X home page</a></p>
</body>
</html>
