Some tips on troubleshooting your man pages follow.
• Some ASCII characters look funny or copy and paste wrong.
On devices with large glyph repertoires, like
UTF-8-capable terminals and PDF, several keyboard glyphs
are mapped to code points outside the Unicode basic Latin
range because that usually results in better typography in
the general case. When documenting GNU/Linux command or C
language syntax, however, this translation is sometimes
not desirable.
To get a 'literal'... ...should be input.
────────────────────────────────────────────
' \(aq
- \-
\ \(rs
^ \(ha
` \(ga
~ \(ti
────────────────────────────────────────────
Additionally, if a neutral double quote (") is needed in a
macro argument, you can use \(dq to get it. You should
not use \(aq for an ordinary apostrophe (as in 'can't') or
\- for an ordinary hyphen (as in 'word-aligned'). Review
subsection 'Portability' above.
• Do I ever need to use an empty macro argument ("")?
Probably not. When this seems necessary, often a shorter
or clearer alternative is available.
Instead of... ...should be considered.
────────────────────────────────────────────────────────────────
.TP "" .TP
────────────────────────────────────────────────────────────────
.BI "" italic-text bold-text .IB italic-text bold-text
────────────────────────────────────────────────────────────────
.TH foo 1 "" "foo 1.2.3" .TH foo 1 yyyy-mm-dd "foo 1.2.3"
────────────────────────────────────────────────────────────────
.IP "" 4n .IP
────────────────────────────────────────────────────────────────
.IP "" 4n .RS 4n
paragraph .P
... paragraph
... .RE
────────────────────────────────────────────────────────────────
.B one two "" three .B one two three
In the title heading (.TH), the date of the page's last
revision is more important than packaging information; it
should not be omitted. Ideally, a page maintainer will
keep both up to date.
.IP is sometimes ill-understood and misused, especially
when no marker argument is supplied—an indentation
argument is not required. By setting an explicit
indentation, you may be overriding the reader's preference
as set with the -rIN option. If your page renders
adequately without one, use the simpler form. If you need
to indent multiple (unmarked) paragraphs, consider an
setting an indented region with .RS and .RE instead.
In the last example, the empty argument does have a subtly
different effect than its suggested replacement; the empty
argument causes an additional space character to be
interpolated between the arguments 'two' and 'three'—but
it is a regular breaking space, so it can be discarded at
the end of an output line. It is better not to be subtle,
particularly with space, which can be overlooked in source
and rendered forms.
• .RS doesn't indent relative to my indented paragraph.
The .RS macro sets the left margin; that is, the position
at which an ordinary paragraph (.P and its synonyms) will
be set. .RS, .IP, .TP, and the deprecated .HP all use the
same default indentation. To create an inset relative to
an indented paragraph, call .RS repeatedly until an
acceptable indentation is achieved, or give .RS an
indentation argument that is at least as much as the
paragraph's indentation amount relative to an adjacent .P
paragraph. See subsection 'Horizontal and vertical
spacing' above for the values.
• .RE doesn't move the inset back to the expected level.
• warning: scaling indicator invalid in context
• warning: number register 'an-saved-marginn' not defined
• warning: number register 'an-saved-prevailing-indentn' not
defined
The .RS macro takes an indentation amount as an argument;
the .RE macro's argument is a specific inset level. .RE 1
goes to the level before any .RS macros were called, .RE 2
goes to the level of the first .RS call you made, and so
forth. If you desire symmetry in your macro calls, simply
issue one .RE without an argument for each .RS that
precedes it.
After calls to the .SH and .SS sectioning macros, all
relative insets are cleared and calls to .RE have no
effect until .RS is used again.
• Do I need to keep typing the indent in a series of .IP calls?
You don't need to if you don't want to change the
indentation. Review subsection 'Horizontal and vertical
spacing' above.
Instead of... ...should be considered.
─────────────────────────────────────────────
.IP \(bu 4n .IP \(bu 4n
paragraph paragraph
.IP \(bu 4n .IP \(bu
another-paragraph another-paragraph
─────────────────────────────────────────────
