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 style.mdoc to stylize the command invocation:

        Then run
        .Ql Nm make Cm install Cm clean .

    which renders as:

    Then run ‘make install clean’.

-   The ‘’ macro is the preferred macro for formatting literal inline fragments. Historically, “” was the preferred way before the deprecation of.

  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 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. 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 “” (“”) macro for quoting. Use the ‘’ (‘’) macro for quoting inside quotes. The use of the "" ("") macro is usually not necessary.

  Variables

-   Use instead of for sysctl(8) variables like kdb.enter.panic.

-   Use the angle brackets <> (“<>”) macro for arguments (file ...) when they are mixed with similarly stylized macros like ~ or, 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>