NAME

details/width —

format of width arguments

DESCRIPTION

The mdoc(7) Bd (display) and Bl (list) macros support many different argument formats for their -offset and -width arguments. This page provides recommendations which ones to use and which ones to avoid, ordered according to decreasing preference.

Standard widths

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 macro.

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 6n, 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:

.Sh ERRORS 
.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:

-offset numbern 
-width numbern

Avoid -width 0n. 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, -inset, or -ohang. For other list types, use a width of at least 1n. While -offset 0n 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 or 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 14 results in a width close to 2n.

Absolute scaling widths

Avoid scaling units like c (centimetre), i (inch), P (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 or f 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.