MAN(7)

💖 MAN — the legacy manual-page formatting language, bestie 💖

(that's MAN(7) from the Miscellaneous Information Manual, if we're being official about it ✨)

---

🌸 NAME 🌸

man — the legacy formatting language for manual pages 🫶

---

🦋 DESCRIPTION 🦋

okay so storytime 📖: the man language was THE standard formatting language for AT&T UNIX manual pages from 1979 to 1989. iconic run, honestly. but—

🚨 DO NOT use it to write new manual pages. 🚨

fr fr. it's a purely presentational language and it lacks support for semantic markup 😭. use the mdoc(7) language instead. periodt. 💅

---

so in a man document, any line that starts with the control character '.' is called a “macro line” ✨. the first word is the macro name, and it usually consists of two capital letters. for a list of portable macros, go peek at “MACRO OVERVIEW” below 👀. the words that come after the macro name are the arguments to the macro.

lines that don't start with the control character are called “text lines” 🎀. they give you free-form text to be printed, and ngl the formatting of that text depends on the respective processing context:

.SH Macro lines change control state.
Text lines are interpreted within the current state.

many aspects of the basic syntax of the man language are based on the roff(7) language 🧚. see the LANGUAGE SYNTAX and MACRO SYNTAX sections in the roff(7) manual for the deets, in particular regarding comments, escape sequences, whitespace, and quoting.

---

every single man document starts with the TH macro, which specifies the document's name and section, followed by the “NAME” section formatted like this:

.TH PROGNAME 1 1979-01-10
.SH NAME
\fBprogname\fR \(en one line about what it does

---

👑 MACRO OVERVIEW 👑

this overview is sorted so that macros of similar purpose are listed together 🫶. deprecated and non-portable macros are not included in the overview, but you can find them in the alphabetical reference below ⬇️.

🎀 Page header and footer meta-data 🎀

• TH — set the title: name section date [source [volume]]
• AT — display AT&T UNIX version in the page footer (<= 1 argument)
• UC — display BSD version in the page footer (<= 1 argument)

🌈 Sections and paragraphs 🌈

• SH — section header (one line)
• SS — subsection header (one line)
• PP — start an undecorated paragraph (no arguments)
• RS, RE — reset the left margin: [width]
• IP — indented paragraph: [head [width]]
• TP — tagged paragraph: [width]
• PD — set vertical paragraph distance: [height]
• in — additional indent: [width]

💅 Physical markup 💅

• B — boldface font
• I — italic font
• SB — small boldface font
• SM — small roman font
• BI — alternate between boldface and italic fonts
• BR — alternate between boldface and roman fonts
• IB — alternate between italic and boldface fonts
• IR — alternate between italic and roman fonts
• RB — alternate between roman and boldface fonts
• RI — alternate between roman and italic fonts

💖 MACRO REFERENCE 💖

ok bestie, this is the canonical list — every single macro, alphabetized, nothing skipped, no cap. 🫶 Wanna know how the scoping of each macro works (like who's in charge until when)? That's over in MACRO SYNTAX, go peek there. ✨

---

AT 📼

Sets the volume for the footer, for compatibility with man pages from AT&T UNIX releases. The optional arguments tell it which release it's from. This macro is an extension that first showed up in 4.3BSD. 💅

B 🅱️

Text is rendered in bold face. periodt.

BI 🎀

Text is rendered alternately in bold and italic. So like, .BI this word and that makes this and and go bold, while word and that go italic. Any whitespace between arguments gets dropped in the output. 🫥

Example:

.BI bold italic bold italic

BR 🌸

Text is rendered alternately in bold face and roman (that's the default font, girly). Whitespace between arguments is omitted in output. Also see BI. 👀

DT 📐

Restore the default tabulator positions — they sit at intervals of 0.5 inches. This does literally nothing unless the tabulator positions got changed with the roff(7) ta request. 😌

EE 🛑

This is a non-standard Version 9 AT&T UNIX extension that GNU later adopted. In mandoc(1), it does the exact same thing as the roff(7) fi request — switch to fill mode. ✨

EX 🚫

Also a non-standard Version 9 AT&T UNIX extension, later adopted by GNU. In mandoc(1), it does the same as the roff(7) nf request — switch to no-fill mode. 💅

HP 📏

Begins a paragraph whose first output line is left-justified, but every line after that is indented. Syntax goes like this:

.HP [width]

The width argument is a roff(7) scaling width. If you specify it, it gets saved for later paragraph left margins; if you don't, the saved-or-default width is used. 🫶

This macro is portable, but it's deprecated, because it has no good representation in HTML output — it usually ends up indistinguishable from PP. 😭

I ✍️

Text is rendered in italics.

IB 🔁

Text is rendered alternately in italics and bold face. Whitespace between arguments is omitted in output. Also see BI. 🎀

IP 🔘

Begins an indented paragraph, syntax:

.IP [head [width]]

The width argument is a roff(7) scaling width that defines the left margin. It's saved for later paragraph left-margins; if unspecified, the saved-or-default width gets used. 💅

The head argument is used as a leading term, flushed to the left margin. Super handy for bulleted paragraphs and stuff like that. 🌟

IR 🦋

Text is rendered alternately in italics and roman (the default font). Whitespace between arguments is omitted in output. Also see BI. 👑

LP 🪞

Just a synonym for PP. that's it, that's the whole macro.

ME 📧

Ends a mailto block that was started with MT. This is a non-standard GNU extension. 🫶

MT 💌

Begins a mailto block. Also a non-standard GNU extension. Syntax:

.MT address
link description to be shown
.ME

OP 🚩

Optional command-line argument. This one is a non-standard DWB extension. Syntax:

.OP key [value]

The key is usually a command-line flag, and value is its argument. 😌

P 🪄

This synonym for PP is an AT&T System III UNIX extension that 4.3BSD later adopted. ✨

PD 📊

Specify the vertical space to be inserted before each new paragraph. Syntax:

.PD [height]

The height argument is a roff(7) scaling width. It defaults to 1v. If you leave the unit off, v is assumed. 💅

This macro affects the spacing before any subsequent instances of HP, IP, LP, P, PP, SH, SS, SY, and TP. so like, it's a whole vibe-shifter for spacing.

PP 📝

Begins an undecorated paragraph. A paragraph's scope gets closed by a subsequent paragraph, sub-section, section, or end of file. The saved paragraph left-margin width gets reset to the default. 🌸

RB 🔄

Text is rendered alternately in roman (the default font) and bold face. Whitespace between arguments is omitted in output. Also see BI. 👀

RE ↩️

Explicitly closes out the scope of a prior RS. The default left margin gets restored to whatever it was before that RS invocation. 💖

Syntax:

.RE [level]

With no argument, the most recent RS block is closed out. If level is 1, all open RS blocks are closed out. Otherwise, level − 1 nested RS blocks stay open. 🫶

RI 🎭

Text is rendered alternately in roman (the default font) and italics. Whitespace between arguments is omitted in output. Also see BI. 🌈

RS 📐

Temporarily resets the default left margin. Syntax:

.RS [width]

The width argument is a roff(7) scaling width. If it's not specified, the saved-or-default width is used. ✨

Also see RE. 👑

SB 🌟

Text is rendered in small size (one point smaller than the default font) bold face. This macro is an extension that probably first appeared in SunOS 4.0, and was later adopted by GNU and by 4.4BSD. 💅

SH 🏛️

Begins a section. A section's scope is only closed by another section or the end of file. The paragraph left-margin width gets reset to the default. 🎀

SM 🤏

Text is rendered in small size — one point smaller than the default font.

SS 🪜

Begins a sub-section. A sub-section's scope is closed by a subsequent sub-section, section, or end of file. The paragraph left-margin width gets reset to the default. ✨

SY 💻

Begins a synopsis block, syntax:

.SY command
arguments
.YS

This is a non-standard GNU extension and it's very rarely used, even in GNU manual pages. Formatting works similar to IP. 👀

TH 👑

Sets the name of the manual page, for use in the page header and footer. Syntax:

.TH name section date [source [volume]]

Conventionally, the document name is given in all caps. The section is usually a single digit, and in a few cases it's followed by a letter. 📚

The recommended date format is YYYY-MM-DD, exactly as specified in the ISO-8601 standard; if the argument doesn't conform, it gets printed verbatim. If the date is empty or not specified, the current date is used. 🗓️

The optional source string specifies the organisation providing the utility. When it's unspecified, mandoc(1) uses its -Ios argument. The volume string replaces the default volume title of the section. 💅

Examples:

.TH CVS 5 1992-02-12 GNU

TP 📌

Begins a paragraph where the head — if it goes past the indentation width — is followed by a newline; if it doesn't, the body follows on the same line, after advancing to the indentation width. Subsequent output lines are indented. 🌸

Syntax:

.TP [width]
head \" one line
body

The width argument is a roff(7) scaling width. If you specify it, it's saved for later paragraph left-margins; if unspecified, the saved-or-default width is used. 🫶

TQ 😶‍🌫️

Like TP, except no vertical spacing is inserted before the paragraph. This is a non-standard GNU extension and it's very rarely used, even in GNU manual pages. 💀

UC 🕰️

Sets the volume for the footer, for compatibility with man pages from BSD releases. The optional first argument specifies which release it's from. This macro is an extension that first appeared in 3BSD. ✨

UE 🔗

Ends a uniform resource identifier block that was started with UR. This is a non-standard GNU extension. 🫶

UR 🌐

Begins a uniform resource identifier block. Also a non-standard GNU extension. Syntax:

.UR uri
link description to be shown
.UE

YS ✅

Ends a synopsis block that was started with SY. This is a non-standard GNU extension. 🎀

in 📥

Indent relative to the current indentation:

.in [width]

If width is signed, the new offset is relative. Otherwise, it's absolute. This value gets reset upon the next paragraph, section, or sub-section. 💅

✨ Line Macros ✨

Line macros are only scoped to the current line — that's their whole thing. The body is zero or more arguments. But plot twist: if a macro is scoped to the next line and its line arguments are empty, then the next line (which has to be text, bestie) gets used instead. So like:

.I
foo

is literally the same as .I foo. 🫶

And now the messy part:

• If next-line macros get invoked consecutively, only the last one is used. 🙈
• If a next-line macro is followed by a non-next-line macro, an error is raised. 💀

The syntax goes like this:

.YO [body...]
[body...]

And here's the full lineup of line macros, with how many args they eat, where they're scoped, and any receipts:

• AT — arguments: <=1, scope: current
• B — arguments: n, scope: next-line
• BI — arguments: n, scope: current
• BR — arguments: n, scope: current
• DT — arguments: 0, scope: current
• EE — arguments: 0, scope: current (Version 9 AT&T UNIX)
• EX — arguments: 0, scope: current (Version 9 AT&T UNIX)
• I — arguments: n, scope: next-line
• IB — arguments: n, scope: current
• IR — arguments: n, scope: current
• OP — arguments: >=1, scope: current (DWB)
• PD — arguments: 1, scope: current
• RB — arguments: n, scope: current
• RI — arguments: n, scope: current
• SB — arguments: n, scope: next-line
• SM — arguments: n, scope: next-line
• TH — arguments: >1, <6, scope: current
• UC — arguments: <=1, scope: current
• in — arguments: 1, scope: current (roff(7))

---

🧱 Block Macros 🧱

Block macros are built different: they've got a head and a body. Just like the in-line ones, the head is scoped to the current line and — in exactly one situation — the next line (yes, the same next-line stipulations from "Line Macros" apply here too, no cap).

The syntax:

.YO [head...]
[head...]
[body...]

So when does the body scope actually close? Depends:

• section — closed by SH
• sub-section — closed by a section or SS
• paragraph — closed by a section, sub-section, HP, IP, LP, P, PP, RE, SY, or TP

And ngl: no closure refers to an explicit block closing macro. That's just how it is.

Also, as a rule, block macros may not be nested. So calling a block macro while another block macro scope is still open — and that open scope isn't implicitly closed — is syntactically incorrect. 🚫

Here's the whole roster:

• HP — arguments: <2, head scope: current, body scope: paragraph
• IP — arguments: <3, head scope: current, body scope: paragraph
• LP — arguments: 0, head scope: current, body scope: paragraph
• ME — arguments: 0, head scope: none, body scope: none (GNU)
• MT — arguments: 1, head scope: current, body scope: to ME (GNU)
• P — arguments: 0, head scope: current, body scope: paragraph
• PP — arguments: 0, head scope: current, body scope: paragraph
• RE — arguments: <=1, head scope: current, body scope: none
• RS — arguments: 1, head scope: current, body scope: to RE
• SH — arguments: >0, head scope: next-line, body scope: section
• SS — arguments: >0, head scope: next-line, body scope: sub-section
• SY — arguments: 1, head scope: current, body scope: to YS (GNU)
• TP — arguments: n, head scope: next-line, body scope: paragraph
• TQ — arguments: n, head scope: next-line, body scope: paragraph (GNU)
• UE — arguments: 0, head scope: current, body scope: none (GNU)
• UR — arguments: 1, head scope: current, body scope: part (GNU)
• YS — arguments: 0, head scope: none, body scope: none (GNU)

One more lil rule: if a block macro is next-line scoped, it may only be followed by in-line macros for decorating text. That's it, that's the boundary. 💅

---

🎨 Font handling 🎨

In man documents you've got two ways to pick a font: the "Physical markup" macros, or roff(7)'s \f font escape sequences. Both valid, bestie. ✨

Here's the tea on how long each one sticks around:

• In text lines, the effect of manual font selection by escape sequences only lasts until the next macro invocation.
• In macro lines, it only lasts until the end of the macro scope.

And heads up: macros like BR open and close a font scope for each argument. So it's giving very much per-argument energy. 👑

---

👀 SEE ALSO 👀

man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)

---

📜 HISTORY 📜

The man language first showed up as a macro package for the roff typesetting system in Version 7 AT&T UNIX. Iconic origin story honestly. 🏛️

The stand-alone implementation that's part of the mandoc(1) utility? That first appeared in OpenBSD 4.6. 🌸

---

💖 AUTHORS 💖

• Douglas McIlroy <m.douglas.mcilroy@dartmouth.edu> — designed and implemented the original version of these macros, wrote the original version of this manual page, and was the first to use them when he edited volume 1 of the Version 7 AT&T UNIX manual pages. main character energy fr. 👑
• James Clark — later rewrote the macros for groff.
• Eric S. Raymond <esr@thyrsus.com> and Werner Lemberg <wl@gnu.org> — added the extended man macros to groff in 2007.
• Kristaps Dzonsons <kristaps@bsd.lv> — wrote the mandoc(1) program and this man reference. 🫶

---

and that's the whole page bestie!! 🎀 This one ships from Debian, dated August 5, 2021, and it's page MAN(7) — go forth and write some gorgeous man pages, you absolute legend 💅✨🦋