nroff(1)

💅 nroff(1) — the girlies' guide to formatting docs for the terminal

okay so bestie, you're looking at nroff(1) from the General Commands Manual section, and honestly? she's iconic. let's get into it 🎀

---

✨ NAME ✨

nroff — format documents with groff for TTY (terminal) devices 🖥️💖

---

🌸 SYNOPSIS 🌸

nroff [-bcCEhikpRStUVz] [-d ctext] [-d string=text] [-K fallback-encoding] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list] [-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression] [-T output-device] [-w warning-category] [-W warning-category] [file ...]

nroff --help

nroff -v
nroff --version

---

🦋 DESCRIPTION 🦋

so nroff formats documents that are written in the groff(7) language — but for typewriter-like devices, aka terminal emulators. think of it as the terminal-glam edition of your doc ✨ GNU nroff literally emulates the AT&T nroff command using groff(1).

nroff generates its output via grotty(1), which is groff's terminal output driver — and she needs to know the character encoding scheme the device is using. consequently, the acceptable arguments to -T are ascii, latin1, utf8, and cp1047 — any others get ignored, no cap 🙈

if neither the GROFF_TYPESETTER environment variable nor the -T command-line option (which overrides the environment variable, she's got main character energy) specifies a (valid) device, nroff consults the locale to select an appropriate output device. she first tries the locale(1) program, then checks several locale-related environment variables — see the “Environment” section below 👇 if all of the foregoing fail, -Tascii is implied. periodt.

the -b, -c, -C, -d, -E, -i, -m, -M, -n, -o, -r, -U, -w, -W, and -z options have the effects described in troff(1). -c and -h imply “-P-c” and “-P-h”, respectively — and -c is also interpreted directly by troff. in addition, this implementation ignores the AT&T nroff options -e, -q, and -s (which are not implemented in groff). 💀

the options -k, -K, -p, -P, -R, -t, and -S are documented in groff(1). -V causes nroff to display the constructed groff command on the standard output stream, but does not execute it 👀. -v and --version show version information about nroff and the programs it runs, while --help displays a usage message — all exit afterward. slay.

---

🔥 EXIT STATUS 🔥

• nroff exits with error status 2 if there was a problem parsing its arguments 😭
• with status 0 if any of the options -V, -v, --version, or --help were specified 👑
• and with the status of groff otherwise.

---

🌈 ENVIRONMENT 🌈

normally, the path separator in environment variables ending with PATH is the colon — but this may vary depending on the operating system. for example, Windows uses a semicolon instead. iykyk 🫶

• GROFF_BIN_PATH — is a colon-separated list of directories in which to search for the groff executable before searching in PATH. if unset, /usr/bin is used.
• GROFF_TYPESETTER — specifies the default output device for groff.
• LC_ALL, LC_CTYPE, LANG, LESSCHARSET — are pattern-matched in this order for contents matching standard character encodings supported by groff in the event no -T option is given and GROFF_TYPESETTER is unset, or the values specified are invalid.

---

🎀 FILES 🎀

• /usr/share/groff/1.23.0/tmac/tty-char.tmac — defines fallback definitions of roff special characters. these definitions more poorly optically approximate typeset output than those of tty.tmac in favor of communicating semantic information. nroff loads it automatically ✨

---

💜 NOTES 💜

pager programs like more(1) and less(1) may require command-line options to correctly handle some output sequences — see grotty(1) for the deets 🧚

---

⭐ SEE ALSO ⭐

groff(1), troff(1), grotty(1), locale(1), roff(7)

---

ngl bestie, if you're piping this into less, go read grotty(1) first — your girl deserves the right flags 💅

and that's the whole vibe check 🦋 this page is from groff 1.23.0, dated 29 October 2024 — the nroff(1) era, and she ate 💖