The master version of this file resides at /home/paulgorman/repo/man/README. A public copy resides at https://paulgorman.org/technical/linux-man-pages.txt.
Linux man pages are produced by groff, a GNU clone of the venerable Unix typesetting system troff.
Groff is a full-fledged typesetting system.
Man pages use a particular set of groff macros, as described in groff_man(7).
Groff instructions appear on their own line, beginning with a dot.
Note that FreeBSD and OpenBSD have adopted a set of macros more semantically specific to man pages called “mdoc” or “mandoc”. See groff_mdoc(7) and mdoc.samples(7).
If we create ~/man/, manpath should find it automatically.
See manpath(1) and /etc/manpath.config.
Put man files in section directories, like ~/man/man1/.
The files need not be gzipped; ~/man/man1/foo.1 is fine.
To avoid collisions with system man pages, customize the section, like ~/man/man1/ls.1m (the “m” is arbitrary).
View the custom man page like man 1m foo.
For man to find personal pages first, add the custom section (e.g. “1m”) at the start of SECTION in /etc/manpath.config.
Run mandb to update the database used for things like whatis.
We keep our custom man pages wherever we want (e.g. $HOME/repo/man/), and use a custom shell script, like:
#!/bin/bash
# Check for local/personal man pages
personal_man_path=$HOME/repo/man/
# If we want custom sections like $MANPATH/manfoo/bar.foo, set
# $personal_man_sections as a colon-delimited list:
# personal_man_sections='foo:paul:99'
# Colorize man pages
man() {
env LESS_TERMCAP_mb=$'\E[01;31m' \
LESS_TERMCAP_md=$'\E[01;38;5;74m' \
LESS_TERMCAP_me=$'\E[0m' \
LESS_TERMCAP_se=$'\E[0m' \
LESS_TERMCAP_so=$'\E[30;47m' \
LESS_TERMCAP_ue=$'\E[0m' \
LESS_TERMCAP_us=$'\E[04;38;5;146m' \
man "$@"
}
if [[ -v $personal_man_sections ]]
then
man --section=${personal_man_sections} --manpath=${personal_man_path} $@ 2> /dev/null
else
man --manpath=${personal_man_path} $@ 2> /dev/null
fi
# If didn't find a custom man page, check the regular man path and sections:
if [[ $? -ne 0 ]]
then
man $@
fi
It still may be desirable to do ln -s ~/repo/man ~/man, so that mandb -u makes whatis foo find our custom pages.
/etc/manpath.config, man-pages(7), man(7), and groff_man(7)man(1) - an interface to the on-line reference manuals (somewhat paraphrased):
Each page argument given to man is normally the name of a program, utility or function.
A section, if provided, will direct man to look only in that section of the manual.
The default action is to search in all of the available sections following a pre-defined order
("1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7" by default, unless overridden by the
SECTION directive in /etc/manpath.config), and to show only the first page
found, even if page exists in several sections.
The table below shows the section numbers of the manual:
1 Executable programs or shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Special files (usually found in /dev)
5 File formats and conventions eg /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non standard]
The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.
bold text type exactly as shown.
italic text replace with appropriate argument.
[-abc] any or all arguments within [ ] are optional.
-a|-b options delimited by | cannot be used together.
argument ... argument is repeatable.
[expression] ... entire expression within [ ] is repeatable.
MANSECT
If $MANSECT is set, its value is a colon-delimited list of sections
and it is used to determine which manual sections to search and in
what order. The default is "1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7",
unless overridden by the SECTION directive in /etc/manpath.config.
From /etc/manpath.config:
# Section names. Manual sections will be searched in the order listed here;
# the default is 1, n, l, 8, 3, 0, 2, 5, 4, 9, 6, 7. Multiple SECTION
# directives may be given for clarity, and will be concatenated together in
# the expected way.
# If a particular extension is not in this list (say, 1mh), it will be
# displayed with the rest of the section it belongs to. The effect of this
# is that you only need to explicitly list extensions if you want to force a
# particular order. Sections with extensions should usually be adjacent to
# their main section (e.g. "1 1mh 8 ...").
#
SECTION 1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7
man-pages(7) - conventions for writing Linux man pages (somewhat paraphrased):
Conventions for source file layout
Limit source code line length to 75 characters where possible
to avoid line-wrapping when patches emailed inline.
New sentences should be started on new lines;
This makes it easier to see the effect of patches.
Title Line
The first command in a man page should be a TH command:
.TH title section date source manual
where:
title The title of the man page in all caps (e.g., MAN-PAGES).
section The section number (e.g., 7).
date The date of the last nontrivial change made to the man page in the form YYYY-MM-DD.
source The source of the command, function, or system call (e.g., GNU or Linux)
manual The title of the manual (e.g., Linux Programmer's Manual).
Sections within a manual page:
NAME e.g., "ls - list directory contents"
SYNOPSIS Syntax of the command and its argument;
boldface for as-is text, and italics for replaceable arguments;
brackets [] surround optional arguments;
pipes | separate choices;
ellipses ... can be repeated.
CONFIGURATION (Normally only for section 4, i.e., special files like in /dev.)
DESCRIPTION What it does.
OPTIONS Command-line options (for sections 1 and 8).
EXIT STATUS Possible exit values and their causes (sections 1 and 8).
RETURN VALUE (For sections 2 and 3)
ERRORS (For sections 2 and 3)
ENVIRONMENT List of environment variables that affect the program and how.
FILES List of configuration, startup, and files on which the program directly operates.
VERSIONS (For sections 2 and 3)
ATTRIBUTES (For sections 2 and 3)
CONFORMING TO Describe any related standards or conventions (e.g., POSIX).
NOTES Miscellaneous notes.
BUGS Limitations, known defects, inconveniences.
EXAMPLE One or more examples demonstrating how it's used.
AUTHORS List of authors; omission of this section is recommended.
SEE ALSO Alphabetical list of related man pages, or possibly other sources.
Hyperlinks
For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)).
This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say:
$ man -Hfirefox-esr pagename
Real minus character
For negative number or options with a leading dash (e.g. "ls -l"), escape the dash:
ls \-l
man(7) - macros to format man pages (somewhat paraphrased):
.\" text
This is a comment.
The only mandatory heading is NAME.
.SH NAME
foo \- my brief description
It is important to follow this format, and use a backslash before the single dash which follows the name.
This is used by mandb(8) to create a database of short descriptions for whatis(1) and apropos(1).
groff_man(7) - groff man macros to support generation of man pages (somewhat paraphrased):
This section describes the available macros for manual pages.
.EX
.EE Example/End Example
.HP [nnn]
Hanging paragraph. Paragraph with hanging left indent (indentation set to nnn).
.IP [designator] [nnn]
Indented paragraph. Paragraph, with designator marking its beginning, indented nnn.
.LP
.PP
.P Mutual aliases. A line break, followed by a vertical space downward.
.RE [nnn]
Restore the previous left margin, or move it left by nnn.
.RS [nnn]
Move left margin to the right by nnn.
.SH [text for heading]
An unnumbered section heading sticking out to the left (indentation of following text is reset to default).
.SS [text for heading]
A secondary unnumbered section heading.
.TH title section [extra1] [extra2] [extra3]
Set title of the man page and the section.
The section must hav ea value between 1 and 8, with an optional string appended (e.g. ".pm").
.TP [nnn]
Paragraph with a label, indented to nnn.
The first line following this macro is used at the label.
.TQ
A header/label continuation for a .TP macro.
(For example, the .LP, .PP, and .P labels above.)
MACROS TO SET FONTS
.B [text]
Bold face [text] or the following line.
.BI text
Alternate bold face and italic text.
.BI this "word and" that
renders 'this' and 'that' as bold, but 'word and' as italic.
.BR text
Alternate bold face and roman.
.I [text]
Italic face [text] or the following line.
.IB text
Alternate italic and bold.
.IR text
Alternate italic and roman.
.RB text
Alternate roman and bold.
.RI text
Alternate roman and italic
.SB [text]
Text on this line or next in bold, one point size smaller than the default font size.
.SM [text]
Text on this line or next one point size smaller than the default font size.
MACROS TO DESCRIBE HYPERLINKS AND EMAIL ADDRESSES
.MT address
.ME [punctuation]
Email address. Text following the address, until .ME is the name:
.MT paul@example.com
Paul Gorman
.ME
.UR url
.UE [punctuation]
Web link.
MACROS TO DESCRIBE COMMAND SYNOPSES
.OP key value
Optional argument. Rendered surrounded by brackets [].
.SY command
Begin synopsis. Rendered with hanging indent.
.YS
Ends synopsis and restored normal indentation.
Example:
.SY foo
.OP \-asdf
.OP \-g bar
.OP \-y bas
.OP \-z bam
.RI [ file
.IR .\|.\|. ]
.YS
Examples:
/usr/share/man/man1/*
/usr/share/man/man2/fcntl.2.gz (suggested as canonical example by man-pages(7))
When editing groff, if vim doesn’t do syntax highlighting, :set syntax=groff.
.\" Margin notes about ls
.TH LS 1m 2015-06-15 "Linux" "Marginalia"
.SH NAME
ls \- margin notes about
.SH SYNOPSIS
.B ls [options]
.SH EXAMPLES
.TP
.B ls \-cr1p
List new files at bottom (i.e. by ctime, reversed, single\-column, append
slash to directories).
.TP
.B ls \-i
List by inode. Handy for removing weirdly named files like:
.HP
find \-inum 17175729 \-exec rm \-i {} \e;
.SH AUTHOR
Paul Gorman
\%http://paulgorman.org/