aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml746
1 files changed, 0 insertions, 746 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
deleted file mode 100644
index c951cbd85e..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
+++ /dev/null
@@ -1,746 +0,0 @@
-<?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. Since 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>