<?xml version='1.0' encoding='ISO-8859-1'?>
<?xml-stylesheet type="text/xsl"
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Process this file with an XSLT processor, e.g. xsltproc: -->
<!-- `xsltproc \
-''-nonet \
-''-param man.charmap.use.subset "0" \
-''-param make.year.ranges "1" \
-''-param make.single.year.ranges "1" \
manpage.xml' -->
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "Daniel">
<!ENTITY dhsurname "Leidert">
<!ENTITY dhemail "daniel.leidert@wgdd.de">
<!-- dhusername could also be set to "&firstname; &surname;". -->
<!ENTITY dhusername "&dhfirstname; &dhsurname;">
<!-- The version information can also be suppressed (just -->
<!-- remove it or comment it out. -->
<!ENTITY dhrelease "0.1.2">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate "2006-08-27">
<!-- TITLE should be something like "User commands", -->
<!-- "&dhpackage; command-line reference" or similar (see e.g. -->
<!-- http://www.tldp.org/HOWTO/Man-Page/q2.html). But limit -->
<!-- the length to 30 chars. -->
<!ENTITY dhtitle "User Manuals">
<!ENTITY dhucpackage "leidert-example">
<!ENTITY dhpackage "foo">
<!-- If the application e.g. belongs to a package like X.org, -->
<!-- this should be set to the its name instead. -->
<!ENTITY dhproduct "&dhpackage;">
<!-- SECTION should be 1-8, maybe w/ subsection other -->
<!-- parameters are allowed: see man(7), man(1) and -->
<!-- http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
<!ENTITY dhsection "1">
]>
<refentry>
<refentryinfo>
<title>&dhtitle;</title>
<productname>&dhpackage;</productname>
<releaseinfo role="version">&dhrelease;</releaseinfo>
<date>&dhdate;</date>
<authorgroup>
<author>
<firstname>Jens</firstname>
<surname>Schweikhardt</surname>
<contrib>Wrote this example manpage for the "Linux Man Page Howto", available at <ulink url="http://www.schweikhardt.net/man_page_howto.html"/> or <ulink url="http://www.faqs.org/docs/Linux-mini/Man-Page.html"/>.</contrib>
<address>
<email>schweikh@schweikhardt.net</email>
</address>
</author>
<author>
<firstname>&dhfirstname;</firstname>
<surname>&dhsurname;</surname>
<contrib>Rewrote and extended the example manpage in DocBook XML for the Debian distribution.</contrib>
<address>
<email>&dhemail;</email>
</address>
</author>
</authorgroup>
<copyright>
<year>1995</year>
<year>1996</year>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<holder>Jens Schweikhardt</holder>
</copyright>
<copyright>
<year>2006</year>
<holder>&dhusername;</holder>
</copyright>
<legalnotice>
<para>The Howto containing this example, was offered under the following conditions:</para>
<para>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</para>
<orderedlist>
<listitem>
<para>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</para>
</listitem>
<listitem>
<para>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</para>
</listitem>
</orderedlist>
<para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
</legalnotice>
</refentryinfo>
<refmeta>
<refentrytitle>&dhucpackage;</refentrytitle>
<manvolnum>&dhsection;</manvolnum>
</refmeta>
<refnamediv>
<refname>&dhpackage;</refname>
<refpurpose>frobnicate the bar library</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&dhpackage;</command>
<arg choice="opt"><option>-bar</option></arg>
<group choice="opt">
<arg choice="plain"><option>-b</option></arg>
<arg choice="plain"><option>--busy</option></arg>
</group>
<group choice="opt">
<arg choice="plain"><option>-c <replaceable>config-file</replaceable></option></arg>
<arg choice="plain"><option>--config=<replaceable>config-file</replaceable></option></arg>
</group>
<arg choice="opt">
<group choice="req">
<arg choice="plain"><option>-e</option></arg>
<arg choice="plain"><option>--example</option></arg>
</group>
<replaceable class="option">this</replaceable>
</arg>
<arg choice="opt">
<group choice="req">
<arg choice="plain"><option>-e</option></arg>
<arg choice="plain"><option>--example</option></arg>
</group>
<group choice="req">
<arg choice="plain"><replaceable>this</replaceable></arg>
<arg choice="plain"><replaceable>that</replaceable></arg>
</group>
</arg>
<arg choice="plain" rep="repeat"><replaceable>file(s)</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>&dhpackage;</command>
<!-- Normally the help and version options make the programs stop
right after outputting the requested information. -->
<group choice="opt">
<arg choice="plain">
<group choice="req">
<arg choice="plain"><option>-h</option></arg>
<arg choice="plain"><option>--help</option></arg>
</group>
</arg>
<arg choice="plain">
<group choice="req">
<arg choice="plain"><option>-v</option></arg>
<arg choice="plain"><option>--version</option></arg>
</group>
</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para><command>&dhpackage;</command> frobnicates the <application>bar</application> library by tweaking internal symbol tables. By default it parses all baz segments and rearranges them in reverse order by time for the <citerefentry><refentrytitle>xyzzy</refentrytitle><manvolnum>1</manvolnum></citerefentry> linker to find them. The symdef entry is then compressed using the <abbrev>WBG</abbrev> (Whiz-Bang-Gizmo) algorithm. All files are processed in the order specified.</para>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<variablelist>
<!-- Use the variablelist.term.separator and the
variablelist.term.break.after parameters to
control the term elements. -->
<varlistentry>
<term><option>-b</option></term>
<term><option>--busy</option></term>
<listitem>
<para>Do not write <quote>busy</quote> to <filename class="devicefile">stdout</filename> while processing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c <replaceable class="parameter">config-file</replaceable></option></term>
<term><option>--config=<replaceable class="parameter">config-file</replaceable></option></term>
<listitem>
<para>Use the alternate system wide <replaceable>config-file</replaceable> instead of the <filename>/etc/foo.conf</filename>. This overrides any <envar>FOOCONF</envar> environment variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option></term>
<listitem>
<para>In addition to the baz segments, also parse the <citerefentry><refentrytitle>blurfl</refentrytitle><manvolnum>3</manvolnum></citerefentry> headers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option></term>
<listitem>
<para>Recursive mode. Operates as fast as lightning at the expense of a megabyte of virtual memory.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="files">
<title>FILES</title>
<variablelist>
<varlistentry>
<term><filename>/etc/foo.conf</filename></term>
<listitem>
<para>The system-wide configuration file. See <citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>${HOME}/.foo.conf</filename></term>
<listitem>
<para>The per-user configuration file. See <citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further details.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="environment">
<title>ENVIONMENT</title>
<variablelist>
<varlistentry>
<term><envar>FOOCONF</envar></term>
<listitem>
<para>The full pathname for an alternate system wide configuration file <citerefentry><refentrytitle>foo.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> (see also <xref linkend="files"/>). Overridden by the <option>-c</option> option.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="diagnostics">
<title>DIAGNOSTICS</title>
<para>The following diagnostics may be issued on <filename class="devicefile">stderr</filename>:</para>
<variablelist>
<varlistentry>
<term><quote><errortext>Bad magic number.</errortext></quote></term>
<listitem>
<para>The input file does not look like an archive file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><quote><errortext>Old style baz segments.</errortext></quote></term>
<listitem>
<para><command>&dhpackage;</command> can only handle new style baz segments. <acronym>COBOL</acronym> object libraries are not supported in this version.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following return codes can be used in scripts:</para>
<segmentedlist>
<segtitle>Errorcode</segtitle>
<segtitle>Errortext</segtitle>
<segtitle>Diagnostic</segtitle>
<seglistitem>
<seg><errorcode>0</errorcode></seg>
<seg><errortext>Program exited normally.</errortext></seg>
<seg>No error. Program ran successfully.</seg>
</seglistitem>
<seglistitem>
<seg><errorcode>1</errorcode></seg>
<seg><errortext>Bad magic number.</errortext></seg>
<seg>The input file does not look like an archive file.</seg>
</seglistitem>
<seglistitem>
<seg><errorcode>2</errorcode></seg>
<seg><errortext>Old style baz segments.</errortext></seg>
<seg><command>&dhpackage;</command> can only handle new style baz segments. <acronym>COBOL</acronym> object libraries are not supported in this version.</seg>
</seglistitem>
</segmentedlist>
</refsect1>
<refsect1 id="bugs">
<!-- Or use this section to tell about upstream BTS. -->
<title>BUGS</title>
<para>The command name should have been chosen more carefully to reflect its purpose.</para>
<para>The upstreams <acronym>BTS</acronym> can be found at <ulink url="http://bugzilla.foo.tld"/>.</para>
</refsect1>
<refsect1 id="see_also">
<title>SEE ALSO</title>
<!-- In alpabetical order. -->
<para><citerefentry>
<refentrytitle>bar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>foo</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>foo.conf</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>xyzzy</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry></para>
<para>The programs are documented fully by <citetitle>The Rise and Fall of a Fooish Bar</citetitle> available via the <application>Info</application> system.</para>
</refsect1>
</refentry>