grotty

grotty [option...] [file...]

-b
    Suppress the use of backspace characters for overstruck characters. This can be useful for terminals that don't handle backspaces correctly or for producing cleaner plain text.

-E
    Do not output error messages generated by the troff preprocessor. This can make the output cleaner by silencing formatting warnings.

-F dir
    Search for font and device description files in the specified dir before checking standard locations. Useful for custom groff setups.

-l
    Use the Latin-1 (ISO 8859-1) character set for output. This is often the default or preferred for terminals supporting Latin-1 characters, allowing for a wider range of displayable glyphs than pure ASCII.

-R
    Do not use reverse line feeds (half-line movements). This might be necessary for some older or specialized terminals that do not support this feature, which is sometimes used for precise vertical positioning.

-u
    Use the underscore character (_) for underlining, rather than backspace-overstriking. This is a simpler method suitable for terminals where backspace-overstrike might not render correctly or be desired.

-v
    Print the version number of grotty to standard error and exit.

-X
    Output XON/XOFF flow control characters. This enables software flow control, which can be useful for managing data flow between grotty and a terminal that supports it.

grotty is a device driver for the GNU roff (groff) text formatting system. Its primary function is to translate groff intermediate output, typically generated by troff or nroff, into a plain ASCII or Latin-1 format suitable for display on character-mode terminals or printers.

While groff itself is a powerful typesetter capable of producing high-quality output formats like PostScript or PDF, grotty specifically handles the rendering for simpler, text-only environments. It achieves text effects like bold, italic, and underlining using techniques such as backspacing and overstriking characters, or by representing italics with underscores. This makes it indispensable for displaying formatted text, most notably Linux man pages, directly in a terminal.

It's often used in pipelines, for example, `man ` (though man typically handles this internally) or `groff -Tlatin1 -P-o -mandoc | grotty`, ensuring that documents formatted with roff macros are legible on any standard terminal.

Limited Formatting: grotty can only render text-based formatting. Complex layouts, images, or advanced typography from groff are lost.
Terminal Dependence: The quality of output (especially for bolding and underlining) depends heavily on the terminal emulator's ability to interpret backspaces and overstrikes.
Character Set Issues: Incorrect terminal encoding settings can lead to garbled characters, particularly when using the -l (Latin-1) option.

grotty achieves effects like bold and italic by using backspace characters (representing \b) to overstrike characters. For example, writing 'o', then backspacing and writing another 'o' can produce a bold 'o'. Underlining is typically done by overstriking with an underscore. This method relies on the terminal correctly interpreting and displaying these sequences, which is standard for most modern terminal emulators.

Although grotty can be invoked directly, it's most commonly used implicitly as part of the groff command or through wrappers like man. For instance, `groff -Tlatin1 -mandoc mydoc.roff | grotty | less` would format a roff document for Latin-1, pipe it through grotty for text rendering, and then display it using the less pager.

grotty is an integral part of the GNU groff project, which began in the late 1980s by James Clark as a free software replacement for the proprietary AT&T troff text formatting system. Prior to groff, formatting for text-only terminals was typically handled by nroff. grotty was developed to provide a robust, modern alternative for rendering groff's intermediate output to plain text, maintaining compatibility with the existing roff ecosystem while offering enhancements and portability across various Unix-like systems. Its design reflects the need to display complex formatted documents like man pages effectively on basic character-mode terminals, which were prevalent at the time of its inception.

groff(1), troff(1), nroff(1), man(1), col(1), less(1)