style/code_samplesdisplaying code samples


.Bd -literal 


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, 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); 
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"")" 
.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 
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.
September 4, 2015