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

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

4 files changed, 725 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile
index e61cbd6a68..4b48491169 100644
--- a/en_US.ISO8859-1/books/fdp-primer/Makefile
+++ b/en_US.ISO8859-1/books/fdp-primer/Makefile
@@ -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
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml
index c3e4d22cd0..d01dd2e2ce 100644
--- a/en_US.ISO8859-1/books/fdp-primer/book.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/book.xml
@@ -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;
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
index 55c9cdcf53..2bfc029895 100644
--- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent
+++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
@@ -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">
diff --git a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
new file mode 100644
index 0000000000..5a66d59d97
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
@@ -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>