Howto Create a Docbook Master For Manpages (techdoc)

This you want to know:

• You want to use a Docbook XML 4.x DTD checking the validity of you xml docbook master - and use "xmlto" along with its xml stylesheets to convert from xml to troff format using libxslt.
• Any <book> can contain multiple <chapter>s, followed by appendix sections like <indexlist> or <reference> sections.
• A docbook master for multiple manpages documenting a complete function list of a project or library... has a base node of type <reference>.
• A <reference> section is a list of <refentry>s. Note that a refentry can carry very different content - defining a manpage is one among multiple optional formats.
• Most docbook master files for a C library will contain a <refentry> list with each having a format of type <funcsynopsis>
• Usually a <refentry> will carry multiple <funcsynopsis> headers along with a single description - like describing "strcmp" and "strncmp" in one manpage file. There will be only one real manpage file with the description plus a series of symlinks (or manpages which use a troff "include" or "forward" statement).
• Therefore: there is a <refmeta> section describing the filename to be generated, a <refnamediv> for the symlinks, a <funcsynopsisdiv> containing multiple <funcsynopsis> headers followed by <refsect1> for the description text.

This is what it looks like:

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<reference><title>Manual Pages</title>

   <refentry id="zzip_rewinddir">
      <refentryinfo>
         <date>0.13.38</date>
         <productname>zziplib</productname>
         <title>zzip_rewinddir</title>
      </refentryinfo>

      <refmeta>               <!-- generates zzip_rewinddir.3 file -->
         <refentrytitle>zzip_rewinddir</refentrytitle>
         <manvolnum>3</manvolnum>
      </refmeta>

      <refnamediv>            <!-- create zzip_seekdir.3 symlink -->
         <refname>zzip_rewinddir</refname>
         <refname>zzip_telldir</refname>
         <refname>zzip_seekdir</refname>
         <refpurpose>seek in directories </refpurpose>
      </refnamediv>

      <refsynopsisdiv><funcsynopsis>
         <funcsynopsisinfo>
            #include &lt;zzip/lib.h&gt;
         </funcsynopsisinfo>

         <funcprototype>           <!-- K&R style prototypes -->
            <funcdef>void  <function>zzip_rewinddir</function></funcdef>
            <paramdef>ZZIP_DIR * dir</paramdef> 
         </funcprototype>
         <funcprototype>
            <funcdef>zzip_off_t <function>zzip_telldir</function></funcdef>
            <paramdef>ZZIP_DIR* dir</paramdef> 
         </funcprototype>
         <funcprototype>
            <funcdef>void <function>zzip_seekdir</function></funcdef>
            <paramdef>ZZIP_DIR* dir</paramdef>
           <paramdef>zzip_off_t offset</paramdef> 
         </funcprototype>
      </funcsynopsis></refsynopsisdiv>

      <refsect1><title>Description</title> 
         <para><function>The zzip_rewinddir function</function> 
            is the equivalent of a <function>rewinddir</function>(2) for...
         </para><para><function>The zzip_telldir function</function> 
            is the equivalent of <function>telldir</function>(2) for...
         </para><para><function>The zzip_seekdir function</function> 
            is the equivalent of <function>seekdir</function>(2) for...
         </para>
      </refsect1>                 <!-- the section title is special -->
                                  <!-- during manpage generation !! -->
      <refsect1><title>Author</title> <itemizedlist>
         <listitem><para>
            Guido Draheim <email>guidod@gmx.de</email>
         </para></listitem>
      </itemizedlist></refsect1>
   </refentry>

   <refentry>....</refentry>
</reference>