• Start
• Documentation
  • PostgreSQL
  • mnoGoSearch
  • Apache 2.4
  • FreeBSD handbook
  • FreeBSD Manual
  • FreeBSD Source
• Tools
• Search
• Protected Area

plain

FreeBSD manual

keyword 1 2 3 4 5 6 7 8 9 n l

download PDF document: style.mdoc.5.pdf

STYLE.MDOC(5) FreeBSD File Formats Manual STYLE.MDOC(5)
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 .Ql 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 .Ql Nm make Cm install Cm clean .
which renders as:
Then run `make install clean'.
- The Ql macro is the preferred macro for formatting literal inline fragments. Historically, Dq Li was the preferred way before the deprecation of Li.
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. # bectl list
It is good to know this command.
Lists - The -width argument to the .Bl macro should match the length of the longest item in the list, e.g.:
.Bl -tag -width "-a address" .It Fl a Ar address Set the address. .It Fl v Print the version. .El
In case the longest item is too long and hurts readability, the recommendation is to set the -width argument to `indent', e.g.:
.Bl -tag -width "indent" .It Cm build Build the port. .It Cm install Install the port. .It Fl install-missing-packages Install the missing packages. .El
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 ...]@where
instead of:
.Sm off .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where .Sm on
which would render as:
--meet=who[,who ...]@where
- Use the Dq ("") macro for quoting. Use the Sq (`') macro for quoting inside quotes. The use of the Qq ("") macro is usually not necessary.
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 man(1), mandoc(1), mdoc(7), style(9)
HISTORY This manual page first appeared in FreeBSD 13.0.
AUTHORS Mateusz Piotrowski <0mp@FreeBSD.org>
FreeBSD 14.0-RELEASE-p11 January 29, 2022 FreeBSD 14.0-RELEASE-p11