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.

                 # make -VLEGAL

             Example 2: Doing Something Different

               The following command does something different.

                 # 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

       It 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
     - 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 13.1-RELEASE-p6        January 29, 2022        FreeBSD 13.1-RELEASE-p6