aboutsummaryrefslogtreecommitdiff
path: root/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc')
-rw-r--r--documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc488
1 files changed, 488 insertions, 0 deletions
diff --git a/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc b/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc
new file mode 100644
index 0000000000..024e3891da
--- /dev/null
+++ b/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc
@@ -0,0 +1,488 @@
+---
+title: Chapter 10. Manual Pages
+prev: books/fdp-primer/po-translations
+next: books/fdp-primer/writing-style
+---
+
+[[manual-pages]]
+= Manual Pages
+:doctype: book
+:toc: macro
+:toclevels: 1
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:source-highlighter: rouge
+:experimental:
+:skip-front-matter:
+:xrefstyle: basic
+:relfileprefix: ../
+:outfilesuffix:
+:sectnumoffset: 10
+
+toc::[]
+
+[[manual-pages-introduction]]
+== Introduction
+
+_Manual pages_, commonly shortened to _man pages_, 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.
+
+Although intended as reference material rather than tutorials, the EXAMPLES sections of manual pages often provide detailed use case.
+
+Manual pages are generally shown interactively by the man:man[1] command. When the user types `man ls`, a search is performed for a manual page matching `ls`. The first matching result is displayed.
+
+[[manual-pages-sections]]
+== Sections
+
+Manual pages are grouped into _sections_. Each section contains manual pages for a specific category of documentation:
+
+[.informaltable]
+[cols="1,1", options="header"]
+|===
+| Section Number
+| Category
+
+
+|1
+|General Commands
+
+|2
+|System Calls
+
+|3
+|Library Functions
+
+|4
+|Kernel Interfaces
+
+|5
+|File Formats
+
+|6
+|Games
+
+|7
+|Miscellaneous
+
+|8
+|System Manager
+
+|9
+|Kernel Developer
+|===
+
+[[manual-pages-markup]]
+== Markup
+
+Various markup forms and rendering programs have been used for manual pages. FreeBSD has used man:groff[7] and the newer man:mandoc[1]. Most existing FreeBSD 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.
+
+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.
+
+Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man:man[1].
+
+[[manual-pages-markup-sections]]
+=== Manual Page Sections
+
+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:
+
+[.informaltable]
+[cols="1,1", options="header"]
+|===
+| Section Name
+| Description
+
+
+|NAME
+|Name of the command
+
+|SYNOPSIS
+|Format of options and arguments
+
+|DESCRIPTION
+|Description of purpose and usage
+
+|ENVIRONMENT
+|Environment settings that affect operation
+
+|EXIT STATUS
+|Error codes returned on exit
+
+|EXAMPLES
+|Examples of usage
+
+|COMPATIBILITY
+|Compatibility with other implementations
+
+|SEE ALSO
+|Cross-reference to related manual pages
+
+|STANDARDS
+|Compatibility with standards like POSIX
+
+|HISTORY
+|History of implementation
+
+|BUGS
+|Known bugs
+
+|AUTHORS
+|People who created the command or wrote the manual page.
+|===
+
+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.
+
+[[manual-pages-markup-macros]]
+=== Macros
+
+man:mdoc[7] markup is based on _macros_. 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:
+
+[.programlisting]
+....
+.Dd December 1, 2015
+.Dt LS 1
+.Sh NAME
+.Nm ls
+.Nd list directory contents
+.Sh SYNOPSIS
+.Nm
+.Op Fl -libxo
+.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
+.Op Fl D Ar format
+.Op Ar
+.Sh DESCRIPTION
+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.
+....
+
+A _Document date_ and _Document title_ are defined.
+A _Section header_ for the NAME section is defined. Then the _Name_ of the command and a one-line _Name description_ are defined.
+The SYNOPSIS section begins. This section describes the command-line options and arguments accepted.
+_Name_ (`.Nm`) has already been defined, and repeating it here just displays the defined value in the text.
+An _Optional_ _Flag_ called `-libxo` is shown. The `Fl` macro adds a dash to the beginning of flags, so this appears in the manual page as `--libxo`.
+A long list of optional single-character flags are shown.
+An optional `-D` flag is defined. If the `-D` flag is given, it must be followed by an _Argument_. The argument is a _format_, 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.
+A final optional argument is defined. Since no name is specified for the argument, the default of `file ...` is used.
+The _Section header_ for the DESCRIPTION section is defined.
+
+When rendered with the command `man ls`, the result displayed on the screen looks like this:
+
+[.programlisting]
+....
+LS(1) FreeBSD General Commands Manual LS(1)
+
+NAME
+ ls - 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.
+....
+
+Optional values are shown inside square brackets.
+
+[[manual-pages-markup-guidelines]]
+=== Markup Guidelines
+
+The man:mdoc[7] markup language is not very strict. For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines:
+
+Only the first letter of macros is upper case::
+Always use upper case for the first letter of a macro and lower case for the remaining letters.
+
+Begin new sentences on new lines::
+Start a new sentence on a new line, do not begin it on the same line as an existing sentence.
+
+Update `.Dd` when making non-trivial changes to a manual page::
+The _Document date_ 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 `.Dd`.
+
+Give examples::
+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.
+
+Include the BSD license::
+Include the BSD license on new manual pages. The preferred license is available from the link:{committers-guide}[Committer's Guide].
+
+[[manual-pages-markup-tricks]]
+=== Markup Tricks
+
+Add a space before punctuation on a line with macros. Example:
+
+[.programlisting]
+....
+.Sh SEE ALSO
+.Xr geom 4 ,
+.Xr boot0cfg 8 ,
+.Xr geom 8 ,
+.Xr gptboot 8
+....
+
+Note how the commas at the end of the `.Xr` lines have been placed after a space. The `.Xr` 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 `4,` or `8,`.
+
+[[manual-pages-markup-important-macros]]
+=== Important Macros
+
+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/shared/man/man*# directories. For example, to search for examples of the `.Bd`_Begin display_ macro:
+
+[source,bash]
+....
+% find /usr/shared/man/man* | xargs zgrep '.Bd'
+....
+
+[[manual-pages-markup-important-macros-organizational]]
+==== Organizational Macros
+
+Some macros are used to define logical blocks of a manual page.
+
+[.informaltable]
+[cols="1,1", options="header"]
+|===
+| Organizational Macro
+| Use
+
+
+|`.Sh`
+|Section header. Followed by the name of the section, traditionally all upper case. Think of these as chapter titles.
+
+|`.Ss`
+|Subsection header. Followed by the name of the subsection. Used to divide a `.Sh` section into subsections.
+
+|`.Bl`
+|Begin list. Start a list of items.
+
+|`.El`
+|End a list.
+
+|`.Bd`
+|Begin display. Begin a special area of text, like an indented area.
+
+|`.Ed`
+|End display.
+|===
+
+[[manual-pages-markup-important-macros-inline]]
+==== Inline Macros
+
+Many macros are used to mark up inline text.
+
+[.informaltable]
+[cols="1,1", options="header"]
+|===
+| Inline Macro
+| Use
+
+
+|`.Nm`
+|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.
+
+|`.Pa`
+|Path to a file. Used to mark up filenames and directory paths.
+|===
+
+[[manual-pages-sample-structures]]
+== Sample Manual Page Structures
+
+This section shows minimal desired man page contents for several common categories of manual pages.
+
+[[manual-pages-sample-structures-section-1-8]]
+=== Section 1 or 8 Command
+
+The preferred basic structure for a section 1 or 8 command:
+
+[.programlisting]
+....
+.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
+....
+
+[[manual-pages-sample-structures-section-4]]
+=== Section 4 Device Driver
+
+The preferred basic structure for a section 4 device driver:
+
+[.programlisting]
+....
+.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
+....
+
+[[manual-pages-sample-structures-section-5]]
+=== Section 5 Configuration File
+
+The preferred basic structure for a section 5 configuration file:
+
+[.programlisting]
+....
+.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
+....
+
+[[manual-pages-testing]]
+== Testing
+
+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 `./` if the new manual page is in the current directory. An absolute path can also be used.
+
+Use man:mandoc[1]'s linter to check for parsing errors:
+
+[source,bash]
+....
+% mandoc -T lint ./mynewmanpage.8
+....
+
+Use package:textproc/igor[] to proofread the manual page:
+
+[source,bash]
+....
+% igor ./mynewmanpage.8
+....
+
+Use man:man[1] to check the final result of your changes:
+
+[source,bash]
+....
+% man ./mynewmanpage.8
+....
+
+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:
+
+[source,bash]
+....
+% man ./mynewmanpage.8 | col -b | vim -R -
+....
+
+Spell-checking with fully-featured dictionaries is encouraged, and can be accomplished by using package:textproc/hunspell[] or package:textproc/aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-aspell[], respectively. For instance:
+
+[source,bash]
+....
+% aspell check --lang=en --mode=nroff ./mynewmanpage.8
+....
+
+[[manual-pages-examples-as-templates]]
+== Example Manual Pages to Use as Templates
+
+Some manual pages are suitable as in-depth examples.
+
+[.informaltable]
+[cols="1,1", options="header"]
+|===
+| Manual Page
+| Path to Source Location
+
+
+|man:cp[1]
+|[.filename]#/usr/src/bin/cp/cp.1#
+
+|man:vt[4]
+|[.filename]#/usr/src/shared/man/man4/vt.4#
+
+|man:crontab[5]
+|[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5#
+
+|man:gpart[8]
+|[.filename]#/usr/src/sbin/geom/class/part/gpart.8#
+|===
+
+[[manual-pages-resources]]
+== Resources
+
+Resources for manual page writers:
+
+* man:man[1]
+* man:mandoc[1]
+* man:groff_mdoc[7]
+* http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc]
+* http://manpages.bsd.lv/history.html[History of UNIX Manpages]