style/code_samples —
displaying code samples
To display a complete multi-line code sample, no matter what the programming
language may be, use the
Bd block macro
with the
-literal argument. Do not mark up
individual parts of the displayed code in any way, format the code just as you
would in a real program. In particular, use tabs and spaces for indentation
just as you would in real code. Depending on how wide the code is and what
looks better, you may or may not use the
-offset
indent argument of the
Bd macro.
If the complete code sample consists of only one single line of code, the
Dl macro can be used instead. Again, do not
mark up individual parts of the displayed code. Usually, put
Pp macros before and after the
Dl line. The
Dl macro automatically takes care of
indentation, so don't attempt manual indentation in this case. If manual
indentation is needed, use
Bd
-literal instead.
To display a short, but complete code sample in-line, the
Ql macro can be used. Obviously, marking up
parts of the code sample or indenting it is not possible in this case.
These literal macros are not well-suited to code containing placeholders because
placeholders should be marked up with
Ar or
Fa macros. If there are placeholders,
marking up all elements of the code individually and wrapping the whole code
in
Bd
-unfilled for multi-line displays and
D1 for single-line displays is usually
preferable.
In the unusual case that an interactive prompt needs to be shown before a
complete sample command line, using the non-literal macros
Bd
-unfilled or
D1 is an option as well. In that case, it
is acceptable to mark up the prompt with
Sy
and the sample command line with
Li.
In the code samples, never use character escape sequences. For example, write
the ‘->’ operator of the C language as ‘->’,
not as ‘\(->’. The only exception is that backslashes need to
be written as ‘\e’, like in any other context, too.
Multi-line code sample from the
strtonum(3)
manual:
.Bd -literal -offset indent
int iterations;
const char *errstr;
iterations = strtonum(optarg, 1, 64, &errstr);
if (errstr)
errx(1, "number of iterations is %s: %s", errstr, optarg);
.Ed
Single-line code sample from the
fseek(3)
manual, explaining what
rewind() does:
.Dl (void)fseek(stream, 0L,
SEEK_SET)
In-line displays from the
rename(2)
manual:
When such a loop exists and two separate processes
attempt to perform
.Ql "rename(""a/foo"", ""b/bar"")"
and
.Ql "rename(""b/bar"", ""a/foo"")" ,
respectively, the system may deadlock attempting
to lock both directories for modification.
An example with placeholders:
The following commands are equivalent:
.Bd -unfilled -offset indent
.Sy chgrp Ar newgroup Ar
.Sy chown Pf : Ar newgroup Ar
.Ed
An example of an UltraSPARC Open Firmware command from the
boot_sparc64(8)
manual:
.D1 Sy ok Li setenv boot-file
sr0a:/bsd
The MACRO REFERENCE section in the
mdoc(7)
manual.
Syntax spanning multiple
lines explains how to mark up syntax descriptions containing placeholders
and semantic markup.
A common misconception is that
Bd and
Dl might inhibit macro processing. That's
not their purpose; instead, they select a different indentation and
justification than the one used by the surrounding text. They may contain both
macros and text. Escaping macro names is required even inside literal
displays.