path: root/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
    The FreeBSD Documentation Project
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="manpages">

  <title>Manual Pages</title>

  <sect1 xml:id="manpages-introduction">
    <title>Introduction</title>

    <para><emphasis>Manual pages</emphasis>, commonly shortened to
      <emphasis>man pages</emphasis>, were conceived as
      readily-available reminders for command syntax, device driver
      details, or configuration file formats.  They have become an
      extremely valuable quick-reference from the command line for
      users, system administrators, and programmers.</para>

    <para>Although intended as reference material rather than
      tutorials, the EXAMPLES sections of manual pages often
      provide detailed use case.</para>

    <para>Manual pages are generally shown interactively by the
      &man.man.1; command.  When the user types
      <command>man ls</command>, a search is performed for a manual
      page matching <literal>ls</literal>.  The first matching result
      is displayed.</para>
  </sect1>

  <sect1 xml:id="manpages-sections">
    <title>Sections</title>

    <para>Manual pages are grouped into <emphasis>sections</emphasis>.
      Each section contains manual pages for a specific category of
      documentation:</para>

    <informaltable>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Section Number</entry>
	    <entry>Category</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry>1</entry>
	    <entry>General Commands</entry>
	  </row>

	  <row>
	    <entry>2</entry>
	    <entry>System Calls</entry>
	  </row>

	  <row>
	    <entry>3</entry>
	    <entry>Library Functions</entry>
	  </row>

	  <row>
	    <entry>4</entry>
	    <entry>Kernel Interfaces</entry>
	  </row>

	  <row>
	    <entry>5</entry>
	    <entry>File Formats</entry>
	  </row>

	  <row>
	    <entry>6</entry>
	    <entry>Games</entry>
	  </row>

	  <row>
	    <entry>7</entry>
	    <entry>Miscellaneous</entry>
	  </row>

	  <row>
	    <entry>8</entry>
	    <entry>System Manager</entry>
	  </row>

	  <row>
	    <entry>9</entry>
	    <entry>Kernel Developer</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 xml:id="manpages-markup">
    <title>Markup</title>

    <para>Various markup forms and rendering programs have been used
      for manual pages.  &os; has used &man.groff.7; and the newer
      &man.mandoc.1;.  Most existing &os; manual pages, and all new
      ones, use the &man.mdoc.7; form of markup.  This is a simple
      line-based markup that is reasonably expressive.  It is mostly
      semantic: parts of text are marked up for what they are, rather
      than for how they should appear when rendered.  There is some
      appearance-based markup which is usually best avoided.</para>

    <para>Manual page source is usually interpreted and displayed to
      the screen interactively.  The source files can be ordinary text
      files or compressed with &man.gzip.1; to save space.</para>

    <para>Manual pages can also be rendered to other formats,
      including PostScript for printing or <acronym>PDF</acronym>
      generation.  See &man.man.1;.</para>

    <sect2 xml:id="manpages-markup-sections">
      <title>Manual Page Sections</title>

      <para>Manual pages are composed of several standard sections.
	Each section has a title in upper case, and the sections for a
	particular type of manual page appear in a specific order.
	For a category 1 General Command manual page, the sections
	are:</para>

      <informaltable>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Section Name</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>NAME</entry>
	      <entry>Name of the command</entry>
	    </row>

	    <row>
	      <entry>SYNOPSIS</entry>
	      <entry>Format of options and arguments</entry>
	    </row>

	    <row>
	      <entry>DESCRIPTION</entry>
	      <entry>Description of purpose and usage</entry>
	    </row>

	    <row>
	      <entry>ENVIRONMENT</entry>
	      <entry>Environment settings that affect
		operation</entry>
	    </row>

	    <row>
	      <entry>EXIT STATUS</entry>
	      <entry>Error codes returned on exit</entry>
	    </row>

	    <row>
	      <entry>EXAMPLES</entry>
	      <entry>Examples of usage</entry>
	    </row>

	    <row>
	      <entry>COMPATIBILITY</entry>
	      <entry>Compatibility with other implementations</entry>
	    </row>

	    <row>
	      <entry>SEE ALSO</entry>
	      <entry>Cross-reference to related manual pages</entry>
	    </row>

	    <row>
	      <entry>STANDARDS</entry>
	      <entry>Compatibility with standards like POSIX</entry>
	    </row>

	    <row>
	      <entry>HISTORY</entry>
	      <entry>History of implementation</entry>
	    </row>

	    <row>
	      <entry>BUGS</entry>
	      <entry>Known bugs</entry>
	    </row>

	    <row>
	      <entry>AUTHORS</entry>
	      <entry>People who created the command or wrote the
		manual page.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>Some sections are optional, and the combination of
	sections for a specific type of manual page vary.  Examples of
	the most common types are shown later in this chapter.</para>
    </sect2>

    <sect2 xml:id="manpages-markup-macros">
      <title>Macros</title>

      <para>&man.mdoc.7; markup is based on
	<emphasis>macros</emphasis>.  Lines that begin with a dot
	contain macro commands, each two or three letters long.  For
	example, consider this portion of the &man.ls.1; manual
	page:</para>

      <programlisting xml:id="manpages-markup-macros-example-ls">
.Dd December 1, 2015  <co xml:id="co-manpages-macro-example-ls-1"/>
.Dt LS 1
.Sh NAME  <co xml:id="co-manpages-macro-example-ls-2"/>
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS  <co xml:id="co-manpages-macro-example-ls-3"/>
.Nm  <co xml:id="co-manpages-macro-example-ls-4"/>
.Op Fl -libxo  <co xml:id="co-manpages-macro-example-ls-5"/>
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,  <co xml:id="co-manpages-macro-example-ls-6"/>
.Op Fl D Ar format  <co xml:id="co-manpages-macro-example-ls-7"/>
.Op Ar  <co xml:id="co-manpages-macro-example-ls-8"/>
.Sh DESCRIPTION  <co xml:id="co-manpages-macro-example-ls-9"/>
For each operand that names a
.Ar file
of a type other than
directory,
.Nm
displays its name as well as any requested,
associated information.
For each operand that names a
.Ar file
of type directory,
.Nm
displays the names of files contained
within that directory, as well as any requested, associated
information.</programlisting>

      <calloutlist>
	<callout arearefs="co-manpages-macro-example-ls-1">
	  <para>A <emphasis>Document date</emphasis> and
	    <emphasis>Document title</emphasis> are defined.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-2">
	  <para>A <emphasis>Section header</emphasis> for the NAME
	    section is defined.  Then the <emphasis>Name</emphasis>
	    of the command and a one-line
	    <emphasis>Name description</emphasis> are defined.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-3">
	  <para>The SYNOPSIS section begins.  This section describes
	    the command-line options and arguments accepted.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-4">
	  <para><emphasis>Name</emphasis> (<literal>.Nm</literal>) has
	    already been defined, and repeating it here just displays
	    the defined value in the text.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-5">
	  <para>An <emphasis>Optional</emphasis>
	    <emphasis>Flag</emphasis> called <literal>-libxo</literal>
	    is shown.  The <literal>Fl</literal> macro adds a dash to
	    the beginning of flags, so this appears in the manual
	    page as <literal>--libxo</literal>.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-6">
	  <para>A long list of optional single-character flags are
	    shown.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-7">
	  <para>An optional <literal>-D</literal> flag is defined.  If
	    the <literal>-D</literal> flag is given, it must be
	    followed by an <emphasis>Argument</emphasis>.  The
	    argument is a <emphasis>format</emphasis>, a string that
	    tells &man.ls.1; what to display and how to display it.
	    Details on the format string are given later in the manual
	    page.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-8">
	  <para>A final optional argument is defined.  Because no name
	    is specified for the argument, the default of
	    <literal>file ...</literal> is used.</para>
	</callout>

	<callout arearefs="co-manpages-macro-example-ls-9">
	  <para>The <emphasis>Section header</emphasis> for the
	    DESCRIPTION section is defined.</para>
	</callout>
      </calloutlist>

      <para>When rendered with the command <command>man ls</command>,
	the result displayed on the screen looks like this:</para>

      <programlisting>LS(1)                   FreeBSD General Commands Manual                  LS(1)

NAME
     ls &mdash; list directory contents

SYNOPSIS
     ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
        [file ...]

DESCRIPTION
     For each operand that names a file of a type other than directory, ls
     displays its name as well as any requested, associated information.  For
     each operand that names a file of type directory, ls displays the names
     of files contained within that directory, as well as any requested,
     associated information.</programlisting>

      <para>Optional values are shown inside square brackets.</para>
    </sect2>

    <sect2 xml:id="manpages-markup-guidelines">
      <title>Markup Guidelines</title>

      <para>The &man.mdoc.7; markup language is not very strict.  For
	clarity and consistency, the &os; Documentation project adds
	some additional style guidelines:</para>

      <variablelist>
	<varlistentry>
	  <term>Only the first letter of macros is upper case</term>

	  <listitem>
	    <para>Always use upper case for the first letter of a
	      macro and lower case for the remaining letters.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Begin new sentences on new lines</term>

	  <listitem>
	    <para>Start a new sentence on a new line, do not begin it
	      on the same line as an existing sentence.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Update <literal>.Dd</literal> when making non-trivial
	    changes to a manual page</term>

	  <listitem>
	    <para>The <emphasis>Document date</emphasis> informs the
	      reader about the last time the manual page was updated.
	      It is important to update whenever non-trivial changes
	      are made to the manual pages.  Trivial changes like
	      spelling or punctuation fixes that do not affect usage
	      can be made without updating
	      <literal>.Dd</literal>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Give examples</term>

	  <listitem>
	    <para>Show the reader examples when possible.  Even
	      trivial examples are valuable, because what is trivial
	      to the writer is not necessarily trivial to the reader.
	      Three examples are a good goal.  A trivial example shows
	      the minimal requirements, a serious example shows actual
	      use, and an in-depth example demonstrates unusual or
	      non-obvious functionality.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Include the BSD license</term>

	  <listitem>
	    <para>Include the BSD license on new manual pages.  The
	      preferred license is available from the <link
		xlink:href="&url.articles.committers-guide;pref-license">Committer's
		Guide</link>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 xml:id="manpages-markup-tricks">
      <title>Markup Tricks</title>

      <para>Add a space before punctuation on a line with
	macros.  Example:</para>

      <programlisting>.Sh SEE ALSO
.Xr geom 4 ,
.Xr boot0cfg 8 ,
.Xr geom 8 ,
.Xr gptboot 8</programlisting>

      <para>Note how the commas at the end of the
	<literal>.Xr</literal> lines have been placed after a space.
	The <literal>.Xr</literal> macro expects two parameters to
	follow it, the name of an external manual page, and a section
	number.  The space separates the punctuation from the section
	number.  Without the space, the external links would
	incorrectly point to section <literal>4,</literal> or
	<literal>8,</literal>.</para>
    </sect2>

    <sect2 xml:id="manpages-markup-important-macros">
      <title>Important Macros</title>

      <para>Some very common macros will be shown here.  For
	more usage examples, see &man.mdoc.7;, &man.groff.mdoc.7;, or
	search for actual use in
	<filename>/usr/share/man/man*</filename> directories.  For
	example, to search for examples of the <literal>.Bd</literal>
	<emphasis>Begin display</emphasis> macro:</para>

      <screen>&prompt.user; <userinput>find /usr/share/man/man* | xargs zgrep '.Bd'</userinput></screen>

      <sect3 xml:id="manpages-markup-important-macros-organizational">
	<title>Organizational Macros</title>

	<para>Some macros are used to define logical blocks of a
	  manual page.</para>

	<informaltable>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Organizational Macro</entry>
		<entry>Use</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal>.Sh</literal></entry>
		<entry>Section header.  Followed by the name of
		  the section, traditionally all upper case.
		  Think of these as chapter titles.</entry>
	      </row>

	      <row>
		<entry><literal>.Ss</literal></entry>
		<entry>Subsection header.  Followed by the name of
		  the subsection.  Used to divide a
		  <literal>.Sh</literal> section into
		  subsections.</entry>
	      </row>

	      <row>
		<entry><literal>.Bl</literal></entry>
		<entry>Begin list.  Start a list of items.</entry>
	      </row>

	      <row>
		<entry><literal>.El</literal></entry>
		<entry>End a list.</entry>
	      </row>

	      <row>
		<entry><literal>.Bd</literal></entry>
		<entry>Begin display.  Begin a special area of
		  text, like an indented area.</entry>
	      </row>

	      <row>
		<entry><literal>.Ed</literal></entry>
		<entry>End display.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </sect3>

      <sect3 xml:id="manpages-markup-important-macros-inline">
	<title>Inline Macros</title>

	<para>Many macros are used to mark up inline text.</para>

	<informaltable>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Inline Macro</entry>
		<entry>Use</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal>.Nm</literal></entry>
		<entry>Name.  Called with a name as a parameter on the
		  first use, then used later without the parameter to
		  display the name that has already been
		  defined.</entry>
	      </row>

	      <row>
		<entry><literal>.Pa</literal></entry>
		<entry>Path to a file.  Used to mark up filenames and
		  directory paths.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </sect3>
    </sect2>
  </sect1>

  <sect1 xml:id="manpages-sample-structures">
    <title>Sample Manual Page Structures</title>

    <para>This section shows minimal desired man page contents for
      several common categories of manual pages.</para>

    <sect2 xml:id="manpages-sample-structures-section-1-8">
      <title>Section 1 or 8 Command</title>

      <para>The preferred basic structure for a section 1 or 8
	command:</para>

      <programlisting xml:id="manpages-sample-structures-section-1-8-sample">.Dd August 25, 2017
.Dt EXAMPLECMD 8
.Os
.Sh NAME
.Nm examplecmd
.Nd "command to demonstrate section 1 and 8 man pages"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility does nothing except demonstrate a trivial but complete
manual page for a section 1 or 8 command.
.Sh SEE ALSO
.Xr exampleconf 5
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
    </sect2>

    <sect2 xml:id="manpages-sample-structures-section-4">
      <title>Section 4 Device Driver</title>

      <para>The preferred basic structure for a section 4 device
	driver:</para>

      <programlisting xml:id="manpages-sample-structures-section-4-sample">.Dd August 25, 2017
.Dt EXAMPLEDRIVER 4
.Os
.Sh NAME
.Nm exampledriver
.Nd "driver to demonstrate section 4 man pages"
.Sh SYNOPSIS
To compile this driver into the kernel, add this line to the
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device exampledriver"
.Ed
.Pp
To load the driver as a module at boot, add this line to
.Xr loader.conf 5 :
.Bd -literal -offset indent
exampledriver_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an opportunity to show a skeleton or template
file for section 4 manual pages.
.Sh HARDWARE
The
.Nm
driver supports these cards from the aptly-named Nonexistent
Technologies:
.Pp
.Bl -bullet -compact
.It
NT X149.2 (single and dual port)
.It
NT X149.8 (single port)
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "flashing green light"
Something bad happened.
.It "flashing red light"
Something really bad happened.
.It "solid black light"
Power cord is unplugged.
.El
.Sh SEE ALSO
.Xr example 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 49.2 .
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
    </sect2>

    <sect2 xml:id="manpages-sample-structures-section-5">
      <title>Section 5 Configuration File</title>

      <para>The preferred basic structure for a section 5
	configuration file:</para>

      <programlisting xml:id="manpages-sample-structures-section-5-sample">.Dd August 25, 2017
.Dt EXAMPLECONF 5
.Os
.Sh NAME
.Nm example.conf
.Nd "config file to demonstrate section 5 man pages"
.Sh DESCRIPTION
.Nm
is an example configuration file.
.Sh SEE ALSO
.Xr example 8
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com</programlisting>
    </sect2>
  </sect1>

  <sect1 xml:id="manpages-testing">
    <title>Testing</title>

    <para>Testing a new manual page can be challenging.  Fortunately
      there are some tools that can assist in the task.  Some of them,
      like &man.man.1;, do not look in the current directory.  It is a
      good idea to prefix the filename with <literal>./</literal> if
      the new manual page is in the current directory.  An absolute
      path can also be used.</para>
    <para>Use &man.mandoc.1;'s linter to check for parsing
      errors:</para>

	<screen>&prompt.user; <userinput>mandoc -T lint ./mynewmanpage.8</userinput></screen>

    <para>Use <package>textproc/igor</package> to proofread the
      manual page:</para>

	<screen>&prompt.user; <userinput>igor ./mynewmanpage.8</userinput></screen>

    <para>Use &man.man.1; to check the final result of your
      changes:</para>

	<screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen>

    <para>You can use &man.col.1; to filter the output of
      &man.man.1; and get rid of the backspace characters before
      loading the result in your favorite editor for
      spell checking:</para>

	<screen>&prompt.user; <userinput>man ./mynewmanpage.8 | col -b | vim -R -</userinput></screen>

    <para>Spell-checking with fully-featured dictionaries is
      encouraged, and can be accomplished by using
	<package>textproc/hunspell</package> or
	<package>textproc/aspell</package> combined with
	<package>textproc/en-hunspell</package> or
	<package>textproc/en-aspell</package>, respectively.
	For instance:</para>

	<screen>&prompt.user; <userinput>aspell check --lang=en --mode=nroff ./mynewmanpage.8</userinput></screen>

  </sect1>

  <sect1 xml:id="manpages-examples-as-templates">
    <title>Example Manual Pages to Use as Templates</title>

    <para>Some manual pages are suitable as in-depth examples.</para>

    <informaltable>
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Manual Page</entry>
	    <entry>Path to Source Location</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry>&man.cp.1;</entry>
	    <entry><filename>/usr/src/bin/cp/cp.1</filename></entry>
	  </row>

	  <row>
	    <entry>&man.vt.4;</entry>
	    <entry><filename>/usr/src/share/man/man4/vt.4</filename></entry>
	  </row>

	  <row>
	    <entry>&man.crontab.5;</entry>
	    <entry><filename>/usr/src/usr.sbin/cron/crontab/crontab.5</filename></entry>
	  </row>

	  <row>
	    <entry>&man.gpart.8;</entry>
	    <entry><filename>/usr/src/sbin/geom/class/part/gpart.8</filename></entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 xml:id="manpages-resources">
    <title>Resources</title>

    <para>Resources for manual page writers:</para>

    <itemizedlist>
      <listitem>
	<para>&man.man.1;</para>
      </listitem>

      <listitem>
	<para>&man.mandoc.1;</para>
      </listitem>

      <listitem>
	<para>&man.groff.mdoc.7;</para>
      </listitem>

      <listitem>
	<para><link
	    xlink:href="http://manpages.bsd.lv/mdoc.html">Practical
	    UNIX Manuals: mdoc</link></para>
      </listitem>

      <listitem>
	<para><link
	    xlink:href="http://manpages.bsd.lv/history.html">History
	    of UNIX Manpages</link></para>
      </listitem>
    </itemizedlist>
  </sect1>
</chapter>