paul@0 | 1 | <?xml version='1.0' encoding='UTF-8'?> |
paul@0 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
paul@0 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
paul@0 | 4 | |
paul@0 | 5 | <!-- |
paul@0 | 6 | |
paul@0 | 7 | `xsltproc -''-nonet \ |
paul@0 | 8 | -''-param man.charmap.use.subset "0" \ |
paul@0 | 9 | -''-param make.year.ranges "1" \ |
paul@0 | 10 | -''-param make.single.year.ranges "1" \ |
paul@0 | 11 | /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl \ |
paul@0 | 12 | manpage.xml' |
paul@0 | 13 | |
paul@0 | 14 | A manual page <package>.<section> will be generated. You may view the |
paul@0 | 15 | manual page with: nroff -man <package>.<section> | less'. A typical entry |
paul@0 | 16 | in a Makefile or Makefile.am is: |
paul@0 | 17 | |
paul@0 | 18 | DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/docbook-xsl/manpages/docbook.xsl |
paul@0 | 19 | XP = xsltproc -''-nonet -''-param man.charmap.use.subset "0" |
paul@0 | 20 | |
paul@0 | 21 | manpage.1: manpage.xml |
paul@0 | 22 | $(XP) $(DB2MAN) $< |
paul@0 | 23 | |
paul@0 | 24 | The xsltproc binary is found in the xsltproc package. The XSL files are in |
paul@0 | 25 | docbook-xsl. A description of the parameters you can use can be found in the |
paul@0 | 26 | docbook-xsl-doc-* packages. Please remember that if you create the nroff |
paul@0 | 27 | version in one of the debian/rules file targets (such as build), you will need |
paul@0 | 28 | to include xsltproc and docbook-xsl in your Build-Depends control field. |
paul@0 | 29 | Alternatively use the xmlto command/package. That will also automatically |
paul@0 | 30 | pull in xsltproc and docbook-xsl. |
paul@0 | 31 | |
paul@0 | 32 | Notes for using docbook2x: docbook2x-man does not automatically create the |
paul@0 | 33 | AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as |
paul@0 | 34 | <refsect1> ... </refsect1>. |
paul@0 | 35 | |
paul@0 | 36 | To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections |
paul@0 | 37 | read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be |
paul@0 | 38 | found in the docbook-xsl-doc-html package. |
paul@0 | 39 | |
paul@0 | 40 | Validation can be done using: `xmllint -''-noout -''-valid manpage.xml` |
paul@0 | 41 | |
paul@0 | 42 | General documentation about man-pages and man-page-formatting: |
paul@0 | 43 | man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/ |
paul@0 | 44 | |
paul@0 | 45 | --> |
paul@0 | 46 | |
paul@0 | 47 | <!-- Fill in your name for FIRSTNAME and SURNAME. --> |
paul@0 | 48 | <!ENTITY dhfirstname "FIRSTNAME"> |
paul@0 | 49 | <!ENTITY dhsurname "SURNAME"> |
paul@0 | 50 | <!-- dhusername could also be set to "&dhfirstname; &dhsurname;". --> |
paul@0 | 51 | <!ENTITY dhusername "Kolab Systems User"> |
paul@0 | 52 | <!ENTITY dhemail "kolab@kolab.example.org"> |
paul@0 | 53 | <!-- SECTION should be 1-8, maybe w/ subsection other parameters are |
paul@0 | 54 | allowed: see man(7), man(1) and |
paul@0 | 55 | http://www.tldp.org/HOWTO/Man-Page/q2.html. --> |
paul@0 | 56 | <!ENTITY dhsection "SECTION"> |
paul@0 | 57 | <!-- TITLE should be something like "User commands" or similar (see |
paul@0 | 58 | http://www.tldp.org/HOWTO/Man-Page/q2.html). --> |
paul@0 | 59 | <!ENTITY dhtitle "libcalendaring User Manual"> |
paul@0 | 60 | <!ENTITY dhucpackage "LIBCALENDARING"> |
paul@0 | 61 | <!ENTITY dhpackage "libcalendaring"> |
paul@0 | 62 | ]> |
paul@0 | 63 | |
paul@0 | 64 | <refentry> |
paul@0 | 65 | <refentryinfo> |
paul@0 | 66 | <title>&dhtitle;</title> |
paul@0 | 67 | <productname>&dhpackage;</productname> |
paul@0 | 68 | <authorgroup> |
paul@0 | 69 | <author> |
paul@0 | 70 | <firstname>&dhfirstname;</firstname> |
paul@0 | 71 | <surname>&dhsurname;</surname> |
paul@0 | 72 | <contrib>Wrote this manpage for the Debian system.</contrib> |
paul@0 | 73 | <address> |
paul@0 | 74 | <email>&dhemail;</email> |
paul@0 | 75 | </address> |
paul@0 | 76 | </author> |
paul@0 | 77 | </authorgroup> |
paul@0 | 78 | <copyright> |
paul@0 | 79 | <year>2007</year> |
paul@0 | 80 | <holder>&dhusername;</holder> |
paul@0 | 81 | </copyright> |
paul@0 | 82 | <legalnotice> |
paul@0 | 83 | <para>This manual page was written for the Debian system |
paul@0 | 84 | (and may be used by others).</para> |
paul@0 | 85 | <para>Permission is granted to copy, distribute and/or modify this |
paul@0 | 86 | document under the terms of the GNU General Public License, |
paul@0 | 87 | Version 2 or (at your option) any later version published by |
paul@0 | 88 | the Free Software Foundation.</para> |
paul@0 | 89 | <para>On Debian systems, the complete text of the GNU General Public |
paul@0 | 90 | License can be found in |
paul@0 | 91 | <filename>/usr/share/common-licenses/GPL</filename>.</para> |
paul@0 | 92 | </legalnotice> |
paul@0 | 93 | </refentryinfo> |
paul@0 | 94 | <refmeta> |
paul@0 | 95 | <refentrytitle>&dhucpackage;</refentrytitle> |
paul@0 | 96 | <manvolnum>&dhsection;</manvolnum> |
paul@0 | 97 | </refmeta> |
paul@0 | 98 | <refnamediv> |
paul@0 | 99 | <refname>&dhpackage;</refname> |
paul@0 | 100 | <refpurpose>program to do something</refpurpose> |
paul@0 | 101 | </refnamediv> |
paul@0 | 102 | <refsynopsisdiv> |
paul@0 | 103 | <cmdsynopsis> |
paul@0 | 104 | <command>&dhpackage;</command> |
paul@0 | 105 | <!-- These are several examples, how syntaxes could look --> |
paul@0 | 106 | <arg choice="plain"><option>-e <replaceable>this</replaceable></option></arg> |
paul@0 | 107 | <arg choice="opt"><option>--example=<parameter>that</parameter></option></arg> |
paul@0 | 108 | <arg choice="opt"> |
paul@0 | 109 | <group choice="req"> |
paul@0 | 110 | <arg choice="plain"><option>-e</option></arg> |
paul@0 | 111 | <arg choice="plain"><option>--example</option></arg> |
paul@0 | 112 | </group> |
paul@0 | 113 | <replaceable class="option">this</replaceable> |
paul@0 | 114 | </arg> |
paul@0 | 115 | <arg choice="opt"> |
paul@0 | 116 | <group choice="req"> |
paul@0 | 117 | <arg choice="plain"><option>-e</option></arg> |
paul@0 | 118 | <arg choice="plain"><option>--example</option></arg> |
paul@0 | 119 | </group> |
paul@0 | 120 | <group choice="req"> |
paul@0 | 121 | <arg choice="plain"><replaceable>this</replaceable></arg> |
paul@0 | 122 | <arg choice="plain"><replaceable>that</replaceable></arg> |
paul@0 | 123 | </group> |
paul@0 | 124 | </arg> |
paul@0 | 125 | </cmdsynopsis> |
paul@0 | 126 | <cmdsynopsis> |
paul@0 | 127 | <command>&dhpackage;</command> |
paul@0 | 128 | <!-- Normally the help and version options make the programs stop |
paul@0 | 129 | right after outputting the requested information. --> |
paul@0 | 130 | <group choice="opt"> |
paul@0 | 131 | <arg choice="plain"> |
paul@0 | 132 | <group choice="req"> |
paul@0 | 133 | <arg choice="plain"><option>-h</option></arg> |
paul@0 | 134 | <arg choice="plain"><option>--help</option></arg> |
paul@0 | 135 | </group> |
paul@0 | 136 | </arg> |
paul@0 | 137 | <arg choice="plain"> |
paul@0 | 138 | <group choice="req"> |
paul@0 | 139 | <arg choice="plain"><option>-v</option></arg> |
paul@0 | 140 | <arg choice="plain"><option>--version</option></arg> |
paul@0 | 141 | </group> |
paul@0 | 142 | </arg> |
paul@0 | 143 | </group> |
paul@0 | 144 | </cmdsynopsis> |
paul@0 | 145 | </refsynopsisdiv> |
paul@0 | 146 | <refsect1 id="description"> |
paul@0 | 147 | <title>DESCRIPTION</title> |
paul@0 | 148 | <para>This manual page documents briefly the |
paul@0 | 149 | <command>&dhpackage;</command> and <command>bar</command> |
paul@0 | 150 | commands.</para> |
paul@0 | 151 | <para>This manual page was written for the Debian distribution |
paul@0 | 152 | because the original program does not have a manual page. |
paul@0 | 153 | Instead, it has documentation in the GNU <citerefentry> |
paul@0 | 154 | <refentrytitle>info</refentrytitle> |
paul@0 | 155 | <manvolnum>1</manvolnum> |
paul@0 | 156 | </citerefentry> format; see below.</para> |
paul@0 | 157 | <para><command>&dhpackage;</command> is a program that...</para> |
paul@0 | 158 | </refsect1> |
paul@0 | 159 | <refsect1 id="options"> |
paul@0 | 160 | <title>OPTIONS</title> |
paul@0 | 161 | <para>The program follows the usual GNU command line syntax, |
paul@0 | 162 | with long options starting with two dashes (`-'). A summary of |
paul@0 | 163 | options is included below. For a complete description, see the |
paul@0 | 164 | <citerefentry> |
paul@0 | 165 | <refentrytitle>info</refentrytitle> |
paul@0 | 166 | <manvolnum>1</manvolnum> |
paul@0 | 167 | </citerefentry> files.</para> |
paul@0 | 168 | <variablelist> |
paul@0 | 169 | <!-- Use the variablelist.term.separator and the |
paul@0 | 170 | variablelist.term.break.after parameters to |
paul@0 | 171 | control the term elements. --> |
paul@0 | 172 | <varlistentry> |
paul@0 | 173 | <term><option>-e <replaceable>this</replaceable></option></term> |
paul@0 | 174 | <term><option>--example=<replaceable>that</replaceable></option></term> |
paul@0 | 175 | <listitem> |
paul@0 | 176 | <para>Does this and that.</para> |
paul@0 | 177 | </listitem> |
paul@0 | 178 | </varlistentry> |
paul@0 | 179 | <varlistentry> |
paul@0 | 180 | <term><option>-h</option></term> |
paul@0 | 181 | <term><option>--help</option></term> |
paul@0 | 182 | <listitem> |
paul@0 | 183 | <para>Show summary of options.</para> |
paul@0 | 184 | </listitem> |
paul@0 | 185 | </varlistentry> |
paul@0 | 186 | <varlistentry> |
paul@0 | 187 | <term><option>-v</option></term> |
paul@0 | 188 | <term><option>--version</option></term> |
paul@0 | 189 | <listitem> |
paul@0 | 190 | <para>Show version of program.</para> |
paul@0 | 191 | </listitem> |
paul@0 | 192 | </varlistentry> |
paul@0 | 193 | </variablelist> |
paul@0 | 194 | </refsect1> |
paul@0 | 195 | <refsect1 id="files"> |
paul@0 | 196 | <title>FILES</title> |
paul@0 | 197 | <variablelist> |
paul@0 | 198 | <varlistentry> |
paul@0 | 199 | <term><filename>/etc/foo.conf</filename></term> |
paul@0 | 200 | <listitem> |
paul@0 | 201 | <para>The system-wide configuration file to control the |
paul@0 | 202 | behaviour of <application>&dhpackage;</application>. See |
paul@0 | 203 | <citerefentry> |
paul@0 | 204 | <refentrytitle>foo.conf</refentrytitle> |
paul@0 | 205 | <manvolnum>5</manvolnum> |
paul@0 | 206 | </citerefentry> for further details.</para> |
paul@0 | 207 | </listitem> |
paul@0 | 208 | </varlistentry> |
paul@0 | 209 | <varlistentry> |
paul@0 | 210 | <term><filename>${HOME}/.foo.conf</filename></term> |
paul@0 | 211 | <listitem> |
paul@0 | 212 | <para>The per-user configuration file to control the |
paul@0 | 213 | behaviour of <application>&dhpackage;</application>. See |
paul@0 | 214 | <citerefentry> |
paul@0 | 215 | <refentrytitle>foo.conf</refentrytitle> |
paul@0 | 216 | <manvolnum>5</manvolnum> |
paul@0 | 217 | </citerefentry> for further details.</para> |
paul@0 | 218 | </listitem> |
paul@0 | 219 | </varlistentry> |
paul@0 | 220 | </variablelist> |
paul@0 | 221 | </refsect1> |
paul@0 | 222 | <refsect1 id="environment"> |
paul@0 | 223 | <title>ENVIRONMENT</title> |
paul@0 | 224 | <variablelist> |
paul@0 | 225 | <varlistentry> |
paul@0 | 226 | <term><envar>FOO_CONF</envar></term> |
paul@0 | 227 | <listitem> |
paul@0 | 228 | <para>If used, the defined file is used as configuration |
paul@0 | 229 | file (see also <xref linkend="files"/>).</para> |
paul@0 | 230 | </listitem> |
paul@0 | 231 | </varlistentry> |
paul@0 | 232 | </variablelist> |
paul@0 | 233 | </refsect1> |
paul@0 | 234 | <refsect1 id="diagnostics"> |
paul@0 | 235 | <title>DIAGNOSTICS</title> |
paul@0 | 236 | <para>The following diagnostics may be issued |
paul@0 | 237 | on <filename class="devicefile">stderr</filename>:</para> |
paul@0 | 238 | <variablelist> |
paul@0 | 239 | <varlistentry> |
paul@0 | 240 | <term><errortext>Bad configuration file. Exiting.</errortext></term> |
paul@0 | 241 | <listitem> |
paul@0 | 242 | <para>The configuration file seems to contain a broken configuration |
paul@0 | 243 | line. Use the <option>--verbose</option> option, to get more info. |
paul@0 | 244 | </para> |
paul@0 | 245 | </listitem> |
paul@0 | 246 | </varlistentry> |
paul@0 | 247 | </variablelist> |
paul@0 | 248 | <para><command>&dhpackage;</command> provides some return codes, that can |
paul@0 | 249 | be used in scripts:</para> |
paul@0 | 250 | <segmentedlist> |
paul@0 | 251 | <segtitle>Code</segtitle> |
paul@0 | 252 | <segtitle>Diagnostic</segtitle> |
paul@0 | 253 | <seglistitem> |
paul@0 | 254 | <seg><errorcode>0</errorcode></seg> |
paul@0 | 255 | <seg>Program exited successfully.</seg> |
paul@0 | 256 | </seglistitem> |
paul@0 | 257 | <seglistitem> |
paul@0 | 258 | <seg><errorcode>1</errorcode></seg> |
paul@0 | 259 | <seg>The configuration file seems to be broken.</seg> |
paul@0 | 260 | </seglistitem> |
paul@0 | 261 | </segmentedlist> |
paul@0 | 262 | </refsect1> |
paul@0 | 263 | <refsect1 id="bugs"> |
paul@0 | 264 | <!-- Or use this section to tell about upstream BTS. --> |
paul@0 | 265 | <title>BUGS</title> |
paul@0 | 266 | <para>The program is currently limited to only work |
paul@0 | 267 | with the <package>foobar</package> library.</para> |
paul@0 | 268 | <para>The upstreams <acronym>BTS</acronym> can be found |
paul@0 | 269 | at <ulink url="http://bugzilla.foo.tld"/>.</para> |
paul@0 | 270 | </refsect1> |
paul@0 | 271 | <refsect1 id="see_also"> |
paul@0 | 272 | <title>SEE ALSO</title> |
paul@0 | 273 | <!-- In alpabetical order. --> |
paul@0 | 274 | <para><citerefentry> |
paul@0 | 275 | <refentrytitle>bar</refentrytitle> |
paul@0 | 276 | <manvolnum>1</manvolnum> |
paul@0 | 277 | </citerefentry>, <citerefentry> |
paul@0 | 278 | <refentrytitle>baz</refentrytitle> |
paul@0 | 279 | <manvolnum>1</manvolnum> |
paul@0 | 280 | </citerefentry>, <citerefentry> |
paul@0 | 281 | <refentrytitle>foo.conf</refentrytitle> |
paul@0 | 282 | <manvolnum>5</manvolnum> |
paul@0 | 283 | </citerefentry></para> |
paul@0 | 284 | <para>The programs are documented fully by <citetitle>The Rise and |
paul@0 | 285 | Fall of a Fooish Bar</citetitle> available via the <citerefentry> |
paul@0 | 286 | <refentrytitle>info</refentrytitle> |
paul@0 | 287 | <manvolnum>1</manvolnum> |
paul@0 | 288 | </citerefentry> system.</para> |
paul@0 | 289 | </refsect1> |
paul@0 | 290 | </refentry> |