The mdoc(7) Bd
(display) and Bl
(list) macros support many different argument formats for their -offset
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
.Bd -type -offset indent
.Bl -type -offset indent -width Ds
whereever these forms can be used with grace.
To get left alignment with no indent, do not use the -offset
option at all. While -offset left
works for the Bd
macro, it is just pointless, and it doesn't work for the Bl
Note that the form -width indent
would be a bad idea. In contrast to the -offset
option, the -width
option does not treat indent
as a special keyword, so -width indent
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.
String length measurements
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.
Macro default widths
A few sections traditionally use macro defaults widths, most notably the Er
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.
Relative scaling widths
It is also acceptable to specify widths relative to the width of the ‘n’ character. In this case, always use the exact following syntax:
. 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 Bl -item
, or -ohang
. For other list types, use a width of at least
. While -offset
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 -offset
option at all.
Never use the relative scaling widths m
, 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 -width
results in a width close to
Absolute scaling widths
Avoid scaling units like c
(pica), and p
(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 definition like u
would be even worse. Using v
is strongly discouraged as well because that unit is intended for vertical measurements and not well suited to horizontal meansurements.
For basic syntax and semantics of the Bd
macros, see the MACRO REFERENCE section in the mdoc(7)
manual. For basic syntax and semantics of numerical width specifications, see the “Scaling Widths” subsection in the roff(7)