linux/debian/manpage.xml.ex

0001 <?xml version='1.0' encoding='UTF-8'?>
0002 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
0003 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
0004
0005 <!--
0006
0007 `xsltproc -''-nonet \
0008           -''-param man.charmap.use.subset "0" \
0009           -''-param make.year.ranges "1" \
0010           -''-param make.single.year.ranges "1" \
0011           /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
0012           manpage.xml'
0013
0014 A manual page <package>.<section> will be generated. You may view the
0015 manual page with: nroff -man <package>.<section> | less'. A typical entry
0016 in a Makefile or Makefile.am is:
0017
0018 DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
0019 XP     = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
0020
0021 manpage.1: manpage.xml
0022         $(XP) $(DB2MAN) $<
0023
0024 The xsltproc binary is found in the xsltproc package. The XSL files are in
0025 docbook-xsl. A description of the parameters you can use can be found in the
0026 docbook-xsl-doc-* packages. Please remember that if you create the nroff
0027 version in one of the debian/rules file targets (such as build), you will need
0028 to include xsltproc and docbook-xsl in your Build-Depends control field.
0029 Alternatively use the xmlto command/package. That will also automatically
0030 pull in xsltproc and docbook-xsl.
0031
0032 Notes for using docbook2x: docbook2x-man does not automatically create the
0033 AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
0034 <refsect1> ... </refsect1>.
0035
0036 To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
0037 read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
0038 found in the docbook-xsl-doc-html package.
0039
0040 Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
0041
0042 General documentation about man-pages and man-page-formatting:
0043 man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
0044
0045 -->
0046
0047   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
0048   <!ENTITY dhfirstname "FIRSTNAME">
0049   <!ENTITY dhsurname   "SURNAME">
0050   <!-- dhusername could also be set to "&firstname; &surname;". -->
0051   <!ENTITY dhusername  "Renaud GUEZENNEC">
0052   <!ENTITY dhemail     "renaud.guezennec@wanadoo.fr">
0053   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
0054        allowed: see man(7), man(1) and
0055        http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
0056   <!ENTITY dhsection   "SECTION">
0057   <!-- TITLE should be something like "User commands" or similar (see
0058        http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
0059   <!ENTITY dhtitle     "rolisteam User Manual">
0060   <!ENTITY dhucpackage "ROLISTEAM">
0061   <!ENTITY dhpackage   "rolisteam">
0062 ]>
0063
0064 <refentry>
0065   <refentryinfo>
0066     <title>&dhtitle;</title>
0067     <productname>&dhpackage;</productname>
0068     <authorgroup>
0069       <author>
0070        <firstname>&dhfirstname;</firstname>
0071         <surname>&dhsurname;</surname>
0072         <contrib>Wrote this manpage for the Debian system.</contrib>
0073         <address>
0074           <email>&dhemail;</email>
0075         </address>
0076       </author>
0077     </authorgroup>
0078     <copyright>
0079       <year>2007</year>
0080       <holder>&dhusername;</holder>
0081     </copyright>
0082     <legalnotice>
0083       <para>This manual page was written for the Debian system
0084         (and may be used by others).</para>
0085       <para>Permission is granted to copy, distribute and/or modify this
0086         document under the terms of the GNU General Public License,
0087         Version 2 or (at your option) any later version published by
0088         the Free Software Foundation.</para>
0089       <para>On Debian systems, the complete text of the GNU General Public
0090         License can be found in
0091         <filename>/usr/share/common-licenses/GPL</filename>.</para>
0092     </legalnotice>
0093   </refentryinfo>
0094   <refmeta>
0095     <refentrytitle>&dhucpackage;</refentrytitle>
0096     <manvolnum>&dhsection;</manvolnum>
0097   </refmeta>
0098   <refnamediv>
0099     <refname>&dhpackage;</refname>
0100     <refpurpose>program to do something</refpurpose>
0101   </refnamediv>
0102   <refsynopsisdiv>
0103     <cmdsynopsis>
0104       <command>&dhpackage;</command>
0105       <!-- These are several examples, how syntaxes could look -->
0106       <arg choice="plain"><option>-e <replaceable>this</replaceable></option></arg>
0107       <arg choice="opt"><option>--example=<parameter>that</parameter></option></arg>
0108       <arg choice="opt">
0109         <group choice="req">
0110           <arg choice="plain"><option>-e</option></arg>
0111           <arg choice="plain"><option>--example</option></arg>
0112         </group>
0113         <replaceable class="option">this</replaceable>
0114       </arg>
0115       <arg choice="opt">
0116         <group choice="req">
0117           <arg choice="plain"><option>-e</option></arg>
0118           <arg choice="plain"><option>--example</option></arg>
0119         </group>
0120         <group choice="req">
0121           <arg choice="plain"><replaceable>this</replaceable></arg>
0122           <arg choice="plain"><replaceable>that</replaceable></arg>
0123         </group>
0124       </arg>
0125     </cmdsynopsis>
0126     <cmdsynopsis>
0127       <command>&dhpackage;</command>
0128       <!-- Normally the help and version options make the programs stop
0129            right after outputting the requested information. -->
0130       <group choice="opt">
0131         <arg choice="plain">
0132           <group choice="req">
0133             <arg choice="plain"><option>-h</option></arg>
0134             <arg choice="plain"><option>--help</option></arg>
0135           </group>
0136         </arg>
0137         <arg choice="plain">
0138           <group choice="req">
0139             <arg choice="plain"><option>-v</option></arg>
0140             <arg choice="plain"><option>--version</option></arg>
0141           </group>
0142         </arg>
0143       </group>
0144     </cmdsynopsis>
0145   </refsynopsisdiv>
0146   <refsect1 id="description">
0147     <title>DESCRIPTION</title>
0148     <para>This manual page documents briefly the
0149       <command>&dhpackage;</command> and <command>bar</command>
0150       commands.</para>
0151     <para>This manual page was written for the Debian distribution
0152       because the original program does not have a manual page.
0153       Instead, it has documentation in the GNU <citerefentry>
0154         <refentrytitle>info</refentrytitle>
0155         <manvolnum>1</manvolnum>
0156       </citerefentry> format; see below.</para>
0157     <para><command>&dhpackage;</command> is a program that...</para>
0158   </refsect1>
0159   <refsect1 id="options">
0160     <title>OPTIONS</title>
0161     <para>The program follows the usual GNU command line syntax,
0162       with long options starting with two dashes (`-').  A summary of
0163       options is included below.  For a complete description, see the
0164       <citerefentry>
0165         <refentrytitle>info</refentrytitle>
0166         <manvolnum>1</manvolnum>
0167       </citerefentry> files.</para>
0168     <variablelist>
0169       <!-- Use the variablelist.term.separator and the
0170            variablelist.term.break.after parameters to
0171            control the term elements. -->
0172       <varlistentry>
0173         <term><option>-e <replaceable>this</replaceable></option></term>
0174         <term><option>--example=<replaceable>that</replaceable></option></term>
0175         <listitem>
0176           <para>Does this and that.</para>
0177         </listitem>
0178       </varlistentry>
0179       <varlistentry>
0180         <term><option>-h</option></term>
0181         <term><option>--help</option></term>
0182         <listitem>
0183           <para>Show summary of options.</para>
0184         </listitem>
0185       </varlistentry>
0186       <varlistentry>
0187         <term><option>-v</option></term>
0188         <term><option>--version</option></term>
0189         <listitem>
0190           <para>Show version of program.</para>
0191         </listitem>
0192       </varlistentry>
0193     </variablelist>
0194   </refsect1>
0195   <refsect1 id="files">
0196     <title>FILES</title>
0197     <variablelist>
0198       <varlistentry>
0199         <term><filename>/etc/foo.conf</filename></term>
0200         <listitem>
0201           <para>The system-wide configuration file to control the
0202             behaviour of <application>&dhpackage;</application>. See
0203             <citerefentry>
0204               <refentrytitle>foo.conf</refentrytitle>
0205               <manvolnum>5</manvolnum>
0206             </citerefentry> for further details.</para>
0207         </listitem>
0208       </varlistentry>
0209       <varlistentry>
0210         <term><filename>${HOME}/.foo.conf</filename></term>
0211         <listitem>
0212           <para>The per-user configuration file to control the
0213              behaviour of <application>&dhpackage;</application>. See
0214              <citerefentry>
0215                <refentrytitle>foo.conf</refentrytitle>
0216                <manvolnum>5</manvolnum>
0217              </citerefentry> for further details.</para>
0218         </listitem>
0219       </varlistentry>
0220     </variablelist>
0221   </refsect1>
0222   <refsect1 id="environment">
0223     <title>ENVIONMENT</title>
0224     <variablelist>
0225       <varlistentry>
0226         <term><envar>FOO_CONF</envar></term>
0227         <listitem>
0228           <para>If used, the defined file is used as configuration
0229             file (see also <xref linkend="files"/>).</para>
0230         </listitem>
0231       </varlistentry>
0232     </variablelist>
0233   </refsect1>
0234   <refsect1 id="diagnostics">
0235     <title>DIAGNOSTICS</title>
0236     <para>The following diagnostics may be issued
0237       on <filename class="devicefile">stderr</filename>:</para>
0238     <variablelist>
0239       <varlistentry>
0240         <term><errortext>Bad configuration file. Exiting.</errortext></term>
0241         <listitem>
0242           <para>The configuration file seems to contain a broken configuration
0243             line. Use the <option>--verbose</option> option, to get more info.
0244           </para>
0245         </listitem>
0246       </varlistentry>
0247     </variablelist>
0248     <para><command>&dhpackage;</command> provides some return codes, that can
0249       be used in scripts:</para>
0250     <segmentedlist>
0251       <segtitle>Code</segtitle>
0252       <segtitle>Diagnostic</segtitle>
0253       <seglistitem>
0254         <seg><errorcode>0</errorcode></seg>
0255         <seg>Program exited successfully.</seg>
0256       </seglistitem>
0257       <seglistitem>
0258         <seg><errorcode>1</errorcode></seg>
0259         <seg>The configuration file seems to be broken.</seg>
0260       </seglistitem>
0261     </segmentedlist>
0262   </refsect1>
0263   <refsect1 id="bugs">
0264     <!-- Or use this section to tell about upstream BTS. -->
0265     <title>BUGS</title>
0266     <para>The program is currently limited to only work
0267       with the <package>foobar</package> library.</para>
0268     <para>The upstreams <acronym>BTS</acronym> can be found
0269       at <ulink url="http://bugzilla.foo.tld"/>.</para>
0270   </refsect1>
0271   <refsect1 id="see_also">
0272     <title>SEE ALSO</title>
0273     <!-- In alpabetical order. -->
0274     <para><citerefentry>
0275         <refentrytitle>bar</refentrytitle>
0276         <manvolnum>1</manvolnum>
0277       </citerefentry>, <citerefentry>
0278         <refentrytitle>baz</refentrytitle>
0279         <manvolnum>1</manvolnum>
0280       </citerefentry>, <citerefentry>
0281         <refentrytitle>foo.conf</refentrytitle>
0282         <manvolnum>5</manvolnum>
0283       </citerefentry></para>
0284     <para>The programs are documented fully by <citetitle>The Rise and
0285       Fall of a Fooish Bar</citetitle> available via the <citerefentry>
0286         <refentrytitle>info</refentrytitle>
0287         <manvolnum>1</manvolnum>
0288       </citerefentry> system.</para>
0289   </refsect1>
0290 </refentry>
0291