diff options
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.adoc | 488 |
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] |