← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to utils/debian/manpage.xml.ex

  • Committer: root
  • Date: 2010-07-04 12:15:06 UTC
  • mto: (0.30.6 release-1.3-dev)
  • mto: This revision was merged to the branch mainline in revision 2259.
  • Revision ID: root@debian-lenny-amd64-20100704121506-v4gosmx61q03hz1f
Added Debian rules

Show diffs side-by-side

added added

removed removed

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