os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add an initial chapter about creating man pages. Much remains to be

Browse source 
added, but at least there will be a place to add it.  And of course
there are bound to be numerous corrections, to which I say the
quintessential BSD response: patches welcome!

Sponsored by:	iXsystems
This commit is contained in:
Warren Block 2017-09-29 20:47:43 +00:00
parent 08731ca7d9
commit 42034e68c1
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=50998
4 changed files with 725 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

5
en_US.ISO8859-1/books/fdp-primer/Makefile
View file

@ -32,6 +32,7 @@ SRCS+= docbook-markup/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= translations/chapter.xml
SRCS+= po-translations/chapter.xml
SRCS+= manpages/chapter.xml
SRCS+= writing-style/chapter.xml
SRCS+= editor-config/chapter.xml
SRCS+= see-also/chapter.xml
@ -44,6 +45,10 @@ IMAGES_LIB+= callouts/2.png
IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
IMAGES_LIB+= callouts/6.png
IMAGES_LIB+= callouts/7.png
IMAGES_LIB+= callouts/8.png
IMAGES_LIB+= callouts/9.png
# Entities
SRCS+= chapters.ent

1
en_US.ISO8859-1/books/fdp-primer/book.xml
View file

@ -261,6 +261,7 @@ The time is 09:18</screen></entry>
&chap.stylesheets;
&chap.translations;
&chap.po-translations;
&chap.manpages;
&chap.writing-style;
&chap.editor-config;
&chap.see-also;

1
en_US.ISO8859-1/books/fdp-primer/chapters.ent
View file

@ -22,6 +22,7 @@
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.translations SYSTEM "translations/chapter.xml">
<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml">
<!ENTITY chap.manpages SYSTEM "manpages/chapter.xml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml">
<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml">
<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml">

718
en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml Normal file
View file

@ -0,0 +1,718 @@
<?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 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>
<tip>
<para>Testing a new manual page can be challenging when it is
not located in the normal manual page search path.
&man.man.1; also does not look in the current directory. If
the new manual page is in the current directory, prefix
the filename with a <literal>./</literal>:</para>
<screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen>
<para>An absolute path can also be used:</para>
<screen>&prompt.user; <userinput>man /home/xsmith/mynewmanpage.8</userinput></screen>
</tip>
<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 spacee, 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-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>