format of width arguments
(list) macros support many different
argument formats for their
arguments. This page provides
recommendations which ones to use and which ones to avoid, ordered according
to decreasing preference.
When aiming for consistency across many manuals, prefer the standard forms
whereever these forms can be used with grace.
To get left alignment with no indent, do not use the
option at all. While
works for the
macro, it is just pointless, and it
doesn't work for the
Note that the form
would be a bad idea. In contrast to
option does not treat
as a special keyword, so
measures the width of the string
“indent” in the current font. Since the string contains six
letters, the width is likely close to
, but probably
not exactly, which is irrelevant for terminal output, but can result in small
misalignment on high-resolution output devices.
When the standard width looks awkward for a particular list, provide the width
in terms of the longest tag string occuring in the list. When using multiple
lists in the vicinity of each other, consider using the same width for all
these lists. If you want to leave a bit more room, you can append one or two
additional characters to the longest tag string. If the string includes blank
characters, don't forget to enclose it in quotes (‘"’).
Do not use macros in the argument specifying the width, that's not portable.
While GNU troff can handle it, mandoc cannot.
A few sections traditionally use macro defaults widths, most notably the
default width in the ERRORS section of
section 2, 3, 4, and 9 manuals, as shown in this example:
.Bl -tag -width Er
.It Bq Er EINVAL
Using macro default widths for other cases is not recommended, it merely
obfuscates the author's intent.
It is also acceptable to specify widths relative to the width of the
‘n’ character. In this case, always use the exact following
. While parsers
usually handle it correctly, formatting varies among implementations, and the
result may occasionally look slightly ugly. If you want a list without any
indentation of the item bodies, consider
. For other list types, use a width
of at least
usually works as
intended, it is pointless. If you don't want any global indentation of the
display or list, just don't use the
option at all.
Never use the relative scaling widths
, they are not fully portable. While
mandoc and GNU troff support them, the Heirloom Doctools do not.
When giving a width numerically, an explicit scaling unit is always required.
Giving a bare number without a unit causes the string length of the number to
be measured, such that
results in a width close to
Avoid scaling units like
(point). Absolute widths that may look
good on one output device will almost certainly be inappropriate for some
other output device.
Obviously, using scaling widths that are explicitly device-dependent by
would be even worse. Using
is strongly discouraged as well because
that unit is intended for vertical measurements and not well suited to
For basic syntax and semantics of the
macros, see the MACRO REFERENCE section
manual. For basic syntax and semantics of numerical width specifications, see
the “Scaling Widths” subsection in the