D
DevynCJohnson
Guest
The man pages are commonly used by many Unixoid (Unix and Unix-like systems) users. As many of us know, in a terminal, a user can type "man SOMETHING" and read the manual for the desired object (usually a command). Many developers that make programs may wish to write their own man pages for their application. However, the programmers must know how to make man pages. Thankfully, this article will explain how to do so.
Sections
Man pages are divided into sections. The sections define what type of object the user is looking-up. For instance, the man pages for device files are under section 4. The sections include
1 - Executable commands/apps that anyone may execute
2 - Kernel System Calls
3 - Subroutines/library-calls; functions provided by libraries
4 - Device files (/dev/*)
5 - Standards for file layouts; the usual structure of the contents of special configuration files
6 - Games
7 - Miscellaneous
8 - Executable commands/apps that can only be used with Root privileges
9 - Linux kernel routines
Deprecated:
n - New documentation
o - Old documentation
l - Local documentation; user created-manpages; local manpages
Other sections may exist such as "3perl" which is for Perl libraries.
General Structure
The man pages themselves are plain text files compressed with gzip. The plain text contains special syntax (called “macros”) used to specify the layout and formatting. The "man" command uncompresses the file and properly displays the text based on the macros (discussed later). The main/global man pages are stored under /usr/share/man/. Inside, there is a folder for various languages besides the system's default language. The man pages in the language used by the system is stored in several directories, one for each section (the 1 through 9). So, there is a directory titled "man1", "man2", "man3", and so forth. Inside each language folder (like "en_AU" on non-Austrlian systems), users will see that a few "man*" folders exist. For instance, on my American English system, there are no "en_US" directories because those man pages are in the "man*" folders. In my "en_AU" directory, there is only "man1".
The files for each man page are named using a special scheme. First, is the object's name. Next, is the section number. Finally, the "gz" extension. So, the man page for the "zless" command is under /usr/share/man/man1/ and is named "zless.1.gz". If a user executed "zcat /usr/share/man/man1/zless.1.gz" or "zless /usr/share/man/man1/zless.1.gz", they could view the raw text for the man page (seen at the end of this article) and see how man pages are written. Running "man /usr/share/man/man1/zless.1.gz" will display the file after being parsed and formatted according to the special syntax.
Layout
Notice that each man page has a general format as represented in the template below. Be sure to use the format seen below when writing the "NAME" section so that the section can be added to the whatis database used by the man -k and apropos commands. Otherwise, the man page will not be included in the whatis database. None of the sections/headers listed below are required. In fact, all headers are optional and developers may place them in a different order than below or use different names. Typically, developers place the headers in a specific order, and it is strongly recommended to do so. The suggested header order is NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, SEE ALSO, BUGS, AUTHOR, and COPYRIGHT.
Below is a basic man page template/format as seen when invoking "man SOMETHING" to get info on an object called "SOMETHING":
Macros
The formatting of a man page can be defined/set by using special code called a macros. The macros is read before the text is displayed on the screen. The "man" command displays the contents of the compressed text file after applying the formatting.
.TH - This sets the man page's title and section. To start a man page, use ".TH" like this (.TH SOMETHING 7 "31 December 2016" "1.0" "SOMETHING User Manual") which is using a structure like this (.TH name section# date version title). The section is specified after ".TH SOMETHING" (where "SOMETHING" is the object's name). Next, the date is typed in double-quotes ("). Afterwards, type the man page's version number in double-quotes followed by the title (SOMETHING User Manual) that is also in double-quotes. Alternately, developers can type ".TH SOMETHING 7". The title will be the default which is different for each section. The date and man page version (if specified) would appear near the bottom of the formatted output.
NOTE: The BSD mdoc-formatted manual pages use ".Dd" instead of ".TH".
.SH - Headers, paragraphs breaks, etc. are defined using ".SH". Type ".SH NAME" to make "NAME" a bold header. If desired, the header's text may be placed in double-quotes. However, if the header contains a space, use quotes to indicate that the quoted text is the whole header.
.SS - This is like ".SH", but this is for making subheaders.
.TP - Hanging tag. Place this on the line before the paragraph to change. In the formatted output, the first word after this tag will be on its own line, and the rest of the paragraph will be indented further. This is used when explaining parameter options. For example, "--option" will not be as indented as its description.
.PP/.P/.LP - These three are the same. They all define a new paragraph. “.PP” is more commonly used than the rest.
.br - This is a line break that provides a blank line.
.RS i - Indent according to "i", where "i" is the amount of indentation. This indent persists until ".RE" is read.
.HP i - This is like ".RS" except this is a hanging indent for the first line of a paragraph.
To escape special characters, use the syntax below. Alternately, some characters (like the dash) are escaped with a backslash (\-).
\&'ESCAPED'
.\" - Single-line comments
The following syntax is used to define the font appearance. Place the macros command before the text that is desired to be changed. For example, to make "Input:" in the text "Input: description" bold, use syntax like this - "\fBInput:\fP description".
\fB - boldface
\fI - italics
\fR - roman type (normal font)
\fP - previously used font; end of previously set font property
Alternately, developers could use this other syntax to define font appearance. However, the macros commands listed below must be at the start of a line. Thus, the desired text to change will be on its own line in the raw file, but the formatted output will show the text in-line with the rest. Not all of the formatting markers below will work on all systems, shells, and terminals.
.B - bold
.BI - bold + italics (used to mention programming-functions)
.BR - bold + roman (used to refer to other man pages)
.I - italics
.IB - italics + bold
.IR - italics + roman
.RB - roman + bold
.RI - roman + italics
.SB - small text + bold
.SM - small text
NOTE: The macros with two attributes (like “.BI”) do not apply both of them to the text. Rather, the attribute is alternated. This means “.BI some text” would alternate appearance, so “some” would be bold and “text” would be italic.
Many other macros commands exist, but those previously mentioned are the most important ones to know. To learn more, read the "man" command's manual page (Shell:$ man man), or go to http://linux.die.net/man/7/man and/or http://linux.die.net/man/7/groff_ms
The template example of "SOMETHING" seen above is shown below (modified) but instead as source code.
Create Man Pages
To create a man page, write the desired text and then add the macros. Next, save the data into a file with the same name as the object being documented; do not use a file extension besides “.#” where “#” is the section number. To preview/check the created man page, type "man /path/to/file" in a terminal. If needed, edit the text and preview again. Once finished, compress the man page file as a gzip with the ".gz" file extension. Be sure to place the section number between the man page's name and the ".gz" file extension so that the final filename looks something like “zless.1.gz”.
To install the man page, place it under /usr/share/man/man*/, replacing the asterisk (*) with the proper section number. However, placing files in that directory requires Root privileges. Users could use one of the two example commands seen below in a terminal to install the man page.
Manpath
Manpath ($MANPATH) is the search path for manual pages just as $PATH is the list of directories to search when executing a command. Systems will use /etc/manpath.config or /etc/man.config to globally define the manpath. Users can define their own local manpath by running "export MANPATH=/home/path/:$MANPATH" or by adding that line to "~/.bashrc" or some other related file. However, not all systems have a global “$MANPATH” variable. Most systems store the man pages under /usr/share/man/. However, some may use /usr/man/ instead. Programs installed under /usr/local/bin/ commonly store their man pages under /usr/local/share/man/ or /usr/local/man/. Usually, /usr/local/man/ is a soft-link to /usr/local/share/man/. Applications installed under /opt/ store their man pages in /opt/man/.
The manpath configuration file also defines which order man will search the sections. Most systems look in section 1 first. In the configuration file, that option will look something like this (SECTION 1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7).
NOTE: Run "man manpath" for more info.
Real Man Page Example
Running "zcat /usr/share/man/man1/zless.1.gz" will display the source code for zless's man page.
Sections
Man pages are divided into sections. The sections define what type of object the user is looking-up. For instance, the man pages for device files are under section 4. The sections include
1 - Executable commands/apps that anyone may execute
2 - Kernel System Calls
3 - Subroutines/library-calls; functions provided by libraries
4 - Device files (/dev/*)
5 - Standards for file layouts; the usual structure of the contents of special configuration files
6 - Games
7 - Miscellaneous
8 - Executable commands/apps that can only be used with Root privileges
9 - Linux kernel routines
Deprecated:
n - New documentation
o - Old documentation
l - Local documentation; user created-manpages; local manpages
Other sections may exist such as "3perl" which is for Perl libraries.
General Structure
The man pages themselves are plain text files compressed with gzip. The plain text contains special syntax (called “macros”) used to specify the layout and formatting. The "man" command uncompresses the file and properly displays the text based on the macros (discussed later). The main/global man pages are stored under /usr/share/man/. Inside, there is a folder for various languages besides the system's default language. The man pages in the language used by the system is stored in several directories, one for each section (the 1 through 9). So, there is a directory titled "man1", "man2", "man3", and so forth. Inside each language folder (like "en_AU" on non-Austrlian systems), users will see that a few "man*" folders exist. For instance, on my American English system, there are no "en_US" directories because those man pages are in the "man*" folders. In my "en_AU" directory, there is only "man1".
The files for each man page are named using a special scheme. First, is the object's name. Next, is the section number. Finally, the "gz" extension. So, the man page for the "zless" command is under /usr/share/man/man1/ and is named "zless.1.gz". If a user executed "zcat /usr/share/man/man1/zless.1.gz" or "zless /usr/share/man/man1/zless.1.gz", they could view the raw text for the man page (seen at the end of this article) and see how man pages are written. Running "man /usr/share/man/man1/zless.1.gz" will display the file after being parsed and formatted according to the special syntax.
Layout
Notice that each man page has a general format as represented in the template below. Be sure to use the format seen below when writing the "NAME" section so that the section can be added to the whatis database used by the man -k and apropos commands. Otherwise, the man page will not be included in the whatis database. None of the sections/headers listed below are required. In fact, all headers are optional and developers may place them in a different order than below or use different names. Typically, developers place the headers in a specific order, and it is strongly recommended to do so. The suggested header order is NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, SEE ALSO, BUGS, AUTHOR, and COPYRIGHT.
Below is a basic man page template/format as seen when invoking "man SOMETHING" to get info on an object called "SOMETHING":
Code:
SOMETHING(SECTION) User Manual SOMETHING(SECTION)
NAME
SOMETHING - briefly describe SOMETHING
SYNOPSIS
formal description of invocation
DESCRIPTION
detailed multi-line description
OPTIONS
explain/list parameters and arguments
EXAMPLES
usage examples
SEE ALSO
list related objects
BUGS
known bugs
AUTHOR
author(s) + contact information
COPYRIGHT
copyright/license infoMacros
The formatting of a man page can be defined/set by using special code called a macros. The macros is read before the text is displayed on the screen. The "man" command displays the contents of the compressed text file after applying the formatting.
.TH - This sets the man page's title and section. To start a man page, use ".TH" like this (.TH SOMETHING 7 "31 December 2016" "1.0" "SOMETHING User Manual") which is using a structure like this (.TH name section# date version title). The section is specified after ".TH SOMETHING" (where "SOMETHING" is the object's name). Next, the date is typed in double-quotes ("). Afterwards, type the man page's version number in double-quotes followed by the title (SOMETHING User Manual) that is also in double-quotes. Alternately, developers can type ".TH SOMETHING 7". The title will be the default which is different for each section. The date and man page version (if specified) would appear near the bottom of the formatted output.
NOTE: The BSD mdoc-formatted manual pages use ".Dd" instead of ".TH".
.SH - Headers, paragraphs breaks, etc. are defined using ".SH". Type ".SH NAME" to make "NAME" a bold header. If desired, the header's text may be placed in double-quotes. However, if the header contains a space, use quotes to indicate that the quoted text is the whole header.
.SS - This is like ".SH", but this is for making subheaders.
.TP - Hanging tag. Place this on the line before the paragraph to change. In the formatted output, the first word after this tag will be on its own line, and the rest of the paragraph will be indented further. This is used when explaining parameter options. For example, "--option" will not be as indented as its description.
.PP/.P/.LP - These three are the same. They all define a new paragraph. “.PP” is more commonly used than the rest.
.br - This is a line break that provides a blank line.
.RS i - Indent according to "i", where "i" is the amount of indentation. This indent persists until ".RE" is read.
.HP i - This is like ".RS" except this is a hanging indent for the first line of a paragraph.
To escape special characters, use the syntax below. Alternately, some characters (like the dash) are escaped with a backslash (\-).
\&'ESCAPED'
.\" - Single-line comments
The following syntax is used to define the font appearance. Place the macros command before the text that is desired to be changed. For example, to make "Input:" in the text "Input: description" bold, use syntax like this - "\fBInput:\fP description".
\fB - boldface
\fI - italics
\fR - roman type (normal font)
\fP - previously used font; end of previously set font property
Alternately, developers could use this other syntax to define font appearance. However, the macros commands listed below must be at the start of a line. Thus, the desired text to change will be on its own line in the raw file, but the formatted output will show the text in-line with the rest. Not all of the formatting markers below will work on all systems, shells, and terminals.
.B - bold
.BI - bold + italics (used to mention programming-functions)
.BR - bold + roman (used to refer to other man pages)
.I - italics
.IB - italics + bold
.IR - italics + roman
.RB - roman + bold
.RI - roman + italics
.SB - small text + bold
.SM - small text
NOTE: The macros with two attributes (like “.BI”) do not apply both of them to the text. Rather, the attribute is alternated. This means “.BI some text” would alternate appearance, so “some” would be bold and “text” would be italic.
Many other macros commands exist, but those previously mentioned are the most important ones to know. To learn more, read the "man" command's manual page (Shell:$ man man), or go to http://linux.die.net/man/7/man and/or http://linux.die.net/man/7/groff_ms
The template example of "SOMETHING" seen above is shown below (modified) but instead as source code.
Code:
.\" Manpage for SOMETHING.
.\" Contact [email protected] to correct errors or typos
.TH SOMETHING 7 "31 December 2016" "1.0" "SOMETHING User Manual"
.SH NAME
SOMETHING \- brief example
.SH SYNOPSIS
SOMETHING [TEXT] [PARAMETERS]
.SH DESCRIPTION
A description of this imaginary object called "SOMETHING".
.SH OPTIONS
.RS 4
.PP
\fB\-\-timeout\fR=\fITIMEOUT\fR
.RE
.SH EXAMPLES
SOMETHING --parameters random-text
.SH "SEE ALSO"
command(1), game(6)
.SH BUGS
No known bugs.
.SH AUTHOR
Some Random Dude ([email protected])
.SH COPYRIGHT
Place a GPL header here or whatever license terms you prefer.Create Man Pages
To create a man page, write the desired text and then add the macros. Next, save the data into a file with the same name as the object being documented; do not use a file extension besides “.#” where “#” is the section number. To preview/check the created man page, type "man /path/to/file" in a terminal. If needed, edit the text and preview again. Once finished, compress the man page file as a gzip with the ".gz" file extension. Be sure to place the section number between the man page's name and the ".gz" file extension so that the final filename looks something like “zless.1.gz”.
To install the man page, place it under /usr/share/man/man*/, replacing the asterisk (*) with the proper section number. However, placing files in that directory requires Root privileges. Users could use one of the two example commands seen below in a terminal to install the man page.
Code:
cp zless /usr/local/man/man1/zless.1 && chmod 0644 /usr/local/man/man1/zless.1 && gzip /usr/local/man/man8/zless.1
gzip zless.1 && install -g 0 -o 0 -m 0644 zless.1.gz /usr/local/man/man1/Manpath
Manpath ($MANPATH) is the search path for manual pages just as $PATH is the list of directories to search when executing a command. Systems will use /etc/manpath.config or /etc/man.config to globally define the manpath. Users can define their own local manpath by running "export MANPATH=/home/path/:$MANPATH" or by adding that line to "~/.bashrc" or some other related file. However, not all systems have a global “$MANPATH” variable. Most systems store the man pages under /usr/share/man/. However, some may use /usr/man/ instead. Programs installed under /usr/local/bin/ commonly store their man pages under /usr/local/share/man/ or /usr/local/man/. Usually, /usr/local/man/ is a soft-link to /usr/local/share/man/. Applications installed under /opt/ store their man pages in /opt/man/.
The manpath configuration file also defines which order man will search the sections. Most systems look in section 1 first. In the configuration file, that option will look something like this (SECTION 1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7).
NOTE: Run "man manpath" for more info.
Real Man Page Example
Running "zcat /usr/share/man/man1/zless.1.gz" will display the source code for zless's man page.
Code:
.TH ZLESS 1
.SH NAME
zless \- file perusal filter for crt viewing of compressed text
.SH SYNOPSIS
.B zless
[ name ... ]
.SH DESCRIPTION
.I Zless
is a filter which allows examination of compressed or plain text files
one screenful at a time on a soft-copy terminal. It is the equivalent of
setting the environment variable LESSOPEN to '|gzip -cdfq -- %s',
and the environment variable LESSMETACHARS to
\&'<space><tab><newline>;*?"()<>[|&^`#\e$%=~',
and then running
.IR less .
However, enough people seem to think that having the
command
.I zless
available is important to be worth providing it.
.SH "SEE ALSO"
zmore(1), less(1)
.SH "BUGS"
.I Zless
does not work with compressed data that is piped to it via standard
input; it requires that input files be specified as arguments.
To read compressed data from a pipe, you can use
.RB ".\|.\|." "|gunzip|less"
instead of
.RB ".\|.\|." "|zless" .
.SH "COPYRIGHT NOTICE"
Copyright \(co 2006, 2007 Free Software Foundation, Inc.
.br
Copyright \(co 1992, 1993 Jean-loup Gailly
.PP
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
.ig
Permission is granted to process this file through troff and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
..
.PP
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
.PP
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
