STYLE.MDOC(5)

🎀 so you wanna write a FreeBSD man page 🎀

okay bestie, welcome to style.mdoc(5) — the FreeBSD manual page style guide, straight out of the File Formats Manual section. this is the whole vibe check for how man pages in the FreeBSD source tree are supposed to look ✨

✨ DESCRIPTION ✨

this file spells out the preferred style for manual pages in the FreeBSD source tree. that's it, that's the assignment 🫶

💅 Code Examples 💅

• use literal formatting for examples and literal shell commands, like this:

Then run
.Ql make install clean .

which renders as:

Then run ‘make install clean’.

the incorrect way would be reaching for 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’.

(yes bestie, same render, different crime — don't do the macro one 🙈)

🧚 Copyright Header 🧚

go refer to style(9). that's it. that's the whole note 🔥

🌸 HARDWARE Section 🌸

driver manuals in section four should have a “HARDWARE” section describing hardware known to work with the driver. this section is drawn verbatim into the Release Hardware Notes, so there's several things to note 👑

• the introductory sentence should be in the form:

The
.Nm
driver supports the following $device_class:

followed by the list of supported hardware.

this defines what driver the subsection is referring to, and lets the reader search through the Hardware Notes not only for the device models they have, but also for the device type they're looking to acquire. iykyk 💖

• the supported hardware should be listed as a bullet list, or — if complexity requires it — a column list. these two list types create very neat subsections with clean starting and stopping points. iconic behaviour, honestly ⭐

🦋 EXAMPLES Section 🦋

• format the “EXAMPLES” section in the following way:

.Bl -tag -width 0n
.It Sy Example 1\&: Doing Something
.Pp
The following command does something.
.Bd -literal -offset 2n
.Ic # make -VLEGAL
.Ed
.It Sy Example 2\&: Doing Something Different
.Pp
The following command does something different.
.Bd -literal -offset 2n
.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.

look at that structure. immaculate. no notes 💅

🌈 Lists 🌈

• the -width argument to the .Bl macro should match the length of the longest rendered 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

matching widths = main character energy. unmatched widths = chaos 😭

🍓 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. that's the whole hierarchy, bestie 👑

💜 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're 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 the difference? the brackets are eating, and the plain one is lowkey giving nothing. use the Aq ✨

---

📁 FILES 📁

• /usr/share/examples/mdoc/ — Examples for writing manual pages. go peek, it's free real estate 🎀

👀 SEE ALSO 👀

man(1), mandoc(1), mdoc(7), roff(7), style(9)

🕰️ HISTORY 🕰️

this manual page first appeared in FreeBSD 13.0. a modern icon, fr fr 🌟

🫶 AUTHORS 🫶

Mateusz Piotrowski <0mp@FreeBSD.org> — thank you for your service, king 👑

---

and that's the whole style guide, bestie — go forth and format 💖

this lil rendering of the page came from the Debian build, dated February 16, 2025 — so if u see this in the wild, that's who's serving it to u 🦋