FM / examples

/usr/share/doc/man-db/examples

Name	Size	Mode	Actions
manpage.example	2963	0644	edit dl rm
manpage.example.mdoc	3811	0644	edit dl rm
manpage.example.pod	2766	0644	edit dl rm
manpage.example.sgml	7015	0644	edit dl rm
manpath.config	5217	0644	edit dl rm

Edit: /usr/share/doc/man-db/examples/manpage.example.sgml (7015B)

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

<!ENTITY manfirstname "<firstname>FIRSTNAME</firstname>">
  <!ENTITY mansurname   "<surname>SURNAME</surname>">
  
  <!ENTITY mandate      "<date>DATE</date>">
  
  <!ENTITY mansection   "<manvolnum>SECTION</manvolnum>">
  <!ENTITY manemail     "<email>EMAIL</email>">
  <!ENTITY manusername  "USERNAME">
  <!ENTITY manucpackage "<refentrytitle>UCPACKAGE</refentrytitle>">
  <!ENTITY manpackage   "PACKAGE">
]>

<refentry>
  <refentryinfo>
    <address>
      &manemail;
    </address>
    <author>
      &manfirstname;
      &mansurname;
    </author>
    <copyright>
      <year>2002</year>
      <holder>&manusername;</holder>
    </copyright>
    &mandate;
  </refentryinfo>
  <refmeta>
    &manucpackage;

&mansection;
  </refmeta>
  <refnamediv>
    <refname>&manpackage;</refname>

<refpurpose>program to do something</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&manpackage;</command>

<group choice="req"><arg>this</arg><arg>that</arg></group>
      <group choice="opt"><arg>-flags</arg></group>
      <group choice="opt">
       <arg>-o <replaceable>option</replaceable></arg>
      </group>
      <arg>argument</arg>
      <arg rep="repeat" choice="opt"><replaceable>more</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

<para>Long drawn-out discussion of <command>&manpackage;</command>.
      It's a good idea to break this up into subsections, like these:</para>

<refsect2>
      <title>A Sample Subsection</title>
      <para></para>
    </refsect2>
    <refsect2>
      <title>Yet Another Sample Subsection</title>

<para>References to the
        <citerefentry>
         <refentrytitle>foo</refentrytitle><manvolnum>SECTION</manvolnum>
        </citerefentry> (or other) manual page should use the
        <markup>&lt;citerefentry&gt;</markup> element as here.
      </para>

<para>Each paragraph within a section is contained within a
        <markup>&lt;para&gt;</markup> tag.</para>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

<para>Some people make this separate from the description.</para>

<variablelist>
      <varlistentry>
        <term><option>this</option>|<option>that</option></term>
        <listitem>
          <para>The user MUST specify either <option>this</option> or
            <option>that</option> to run the program. The { and } braces
            mean one of the enclosed is required. The bar (|) separates
            exclusive options (i.e. you cannot have both at once.)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-o</option></term>
        <listitem>
          <para>Pass the user-supplied <replaceable>option</replaceable> to
            <command>foo</command> to change its behaviour. The fact that
            <replaceable>option</replaceable> is underlined or in italics
            means that the user replaces it with a valid value for this
            option. The [ and ] brackets mean it isn't required.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>argument</option></term>
        <listitem>
          <para>The last <option>argument</option> is required, because it
            is not in brackets.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>more</option></term>
        <listitem>
          <para>means that the user can optionally specify additional
            arguments at the end. The ellipses (...) indicate one or more of
            this parameter is allowed.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>RETURN VALUE</title>

<para>What the program or function returns if successful.</para>
  </refsect1>
  <refsect1>
    <title>ERRORS</title>

<para>Return codes, either exit status or errno settings.</para>
  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>

<para>Give some example uses of the program.</para>
  </refsect1>
  <refsect1>
    <title>ENVIRONMENT</title>

<para>Environment variables this program might care about.</para>
  </refsect1>
  <refsect1>
    <title>FILES</title>

<para>All files used by the program. Typical usage is like this:</para>

<variablelist>
      <varlistentry>
        <term><filename>/usr/man</filename></term>
        <listitem><para>default man tree</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/usr/man/man*/*.*</filename></term>
        <listitem><para>unformatted (nroff source) man pages</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>NOTES</title>

<para>Miscellaneous commentary.</para>
  </refsect1>
  <refsect1>
    <title>CAVEATS</title>

<para>Things to take special care with, sometimes called WARNINGS.</para>
  </refsect1>
  <refsect1>
    <title>DIAGNOSTICS</title>

<para>All the possible error messages the program can print out, what
      they mean, and how to correct them if applicable.</para>
  </refsect1>
  <refsect1>
    <title>BUGS</title>

<para>Things that are broken or just don't work quite right.</para>
  </refsect1>
  <refsect1>
    <title>RESTRICTIONS</title>

<para>Bugs you don't plan to fix. :-)</para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

<para>Who wrote it (or AUTHORS if multiple).</para>
  </refsect1>
  <refsect1>
    <title>HISTORY</title>

<para>Programs derived from other sources sometimes have this.</para>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

<para>Other man pages to check out, like man(1), man(7), mandb(8),
      catman(8).</para>
  </refsect1>
</refentry>

cmd: