NAME
style.mdoc
—
FreeBSD
mdoc(7) file style guide
DESCRIPTION
This file specifies the preferred style for manual pages in the FreeBSD source tree.Code Examples
- Use literal formatting for examples and literal shell commands, e.g.:
Then run .Dq Li make install clean .
which renders as:
Then run “make install clean
”.The incorrect way would be to use macros like Nm to stylize the command invocation:
Then run .Dq Nm make Cm install Cm clean .
which renders as:
Then run “make
install
clean
”.
EXAMPLES Section
- Format the EXAMPLES section in the
following way:
.Bl -tag -width 0n .It Sy Example 1\&: No Doing Something .Pp The following command does something. .Bd -literal -offset 2n .Li # Ic make -VLEGAL .Ed .It Sy Example 2\&: No Doing Something Different .Pp The following command does something different. .Bd -literal -offset 2n .Li # Ic bectl list .Ed .Pp It is good to know this command. .El
which renders as:
- Example 1: Doing Something
-
The following command does something.
#
make -VLEGAL
- Example 2: Doing Something Different
-
The following command does something different.
#
bectl list
It is good to know this command.
Synopsis Formatting
- Do not put whitespace between alternative parameters separated with a pipe
(“|”), e.g.:
.Cm compression Cm on Ns | Ns Cm off .Cm install Fl -all Ns | Ns Ar portname Ar ...
which in the SYNOPSIS section is rendered as:
compression
on
|off
install
--all
|portname ... - Use Cm to stylize characters that are command modifiers
(e.g., “,”, “@” or “=”). For
example:
.Sm off .Fl -meet Cm = Ar who Oo Cm , Ar who " " Ar "..." Oc Cm @ Ar where .Sm on
which renders as:
--meet
=
who[,
who ...]@
whereinstead of:
.Sm off .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where .Sm on
which would render as:
--meet
=who[,who ...]@whereIt is important to realize that in the correct example, “,”, “@” and “=” are stylized with Cm. At the same time, the square brackets (“[]”) are not stylized as they do not belong to the syntax of the
--meet
flag.
Quoting
Variables
- Use Va instead of Dv for sysctl(8) variables like kdb.enter.panic.
- Use the angle brackets
Aq
(“<>”) macro for arguments
(Ar) when
they are mixed with similarly stylized macros like
Pa or
Va, e.g.:
.Va critical_filesystems_ Ns Aq Ar type
which renders as:
critical_filesystems_⟨type⟩instead of:
.Va critical_filesystems_ Ns Ar type
that would be rendered as:
critical_filesystems_type
SEE ALSO
HISTORY
This manual page first appeared in FreeBSD 13.0.
AUTHORS
Mateusz Piotrowski <0mp@FreeBSD.org>