style/multiline —
syntax spanning multiple lines
In rare cases, manual pages need to document syntax that extends across multiple
lines, either because line breaks are syntactically signficant in the language
in question or because the syntax is conventionally indented for readability.
A
Bd
-unfilled block can be used to get the line
breaks at the required places and to specify a global indentation if desired.
Inside that block, semantic macros like
Ic,
Fl, and
Ar can be employed as usual.
If the block contains any text input lines that require indentation, just begin
these lines with the desired number of blank characters.
A minor annoyance is that an unfilled display does not provide any natural way
to indent the text resulting from macro lines. As a workaround, use the
No macro and provide a double quoted
argument containing one less than the desired number of blank characters.
Here is an example from the
sh(1) manual:
.Bd -unfilled -offset indent
.Ic if Ar conditional
.Ic then
.No " " Ar command
.No " " Ar ...
.Ic elif Ar conditional
.Ic then
.No " " Ar command
.No " " Ar ...
.Ic else
.No " " Ar command
.No " " Ar ...
.Ic fi
.Ed
The MACRO REFERENCE section in the
mdoc(7)
manual.
Displaying code samples
explains how to mark up complete example code that does not contain any
placeholders.