Name

gnroff - format documents with groff for terminal (“TTY”) devices

Synopsis

gnroff [-abcCEhikpRStUVzZ] [-d ctext] [-d string=text] [-D fallback-input-encoding] [-I inclusion-directory] [-K input-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 ...]

gnroff --help

gnroff -v [other-nroff-option ...]

gnroff --version [other-nroff-option ...]

Description

gnroff formats documents written in the groff(7) language for typewriter-like devices such as terminal emulators. GNU nroff emulates the AT&T nroff command using groff(1). gnroff generates output via grotty(1), groff's terminal output driver, which needs to know the character encoding scheme used by the device. Consequently, acceptable arguments to the -T option are ascii, latin1, and utf8; any others are ignored. If neither the GROFF_TYPESETTER environment variable nor the -T command-line option (which overrides the environment variable) specifies a (valid) device, gnroff consults the locale to select an appropriate output device. It first tries the locale(1) program, then checks several locale-related environment variables; see section “Environment” below. If all of the foregoing fail, gnroff assumes “-T ascii”.

The -a, -b, -c, -C, -d, -E, -i, -I, -m, -M, -n, -o, -r, -U, -w, -W, and -z options have the effects described in gtroff(1). -c and -h imply “-P -c” and “-P -h”, respectively; -c is also meaningful to gtroff itself. Further, GNU nroff ignores the AT&T nroff options -e, -q, and -s. groff(1) documents options -D, -k, -K, -p, -P, -R, -t, -S, and -Z. -V causes gnroff to display the constructed groff command on the standard output stream, but does not execute it. -v and --version show version information about gnroff and the programs it runs, while --help displays a usage message; all exit afterward.

Exit status

gnroff exits with 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; this may vary depending on the operating system. For example, Windows uses a semicolon instead.

GROFF_BIN_PATH: Locate groff commands in these directories, followed by those in PATH. If not set, the installation directory of GNU roff executables, /usr/bin, is searched before PATH.
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.24.1/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).