Control grotty Output for Readable Terminal Man Pages

You will use grotty through groff to produce terminal output with working bold, italics, colour and links, then switch to its older overstrike format when a pager or terminal cannot handle control sequences. The examples match GNU groff 1.23.0, supplied here by groff-base 1.23.0-3build2.

Allow about 10 minutes. You need a shell, groff and grotty. No elevated privileges are needed because the examples read a document and write to standard output. Do not send untrusted output containing terminal control sequences straight to a terminal until you understand where it came from.

1. Check the installed driver

grotty is the TTY output driver for troff. In normal use, groff selects it when you choose a terminal device such as utf8, ascii or latin1. Check both the wrapper and the driver before debugging a display problem.

$ command -v groff grotty
/usr/bin/groff
/usr/bin/grotty
$ grotty --version
GNU grotty (groff) version 1.23.0

If the command is missing, install the distribution's groff package using its normal package-management process. That is an administrative change, so stop and check the package name for your distribution before using sudo.

Checkpoint: identify the output path

For a man page, the convenient path is man or groff selecting a terminal device. Directly piping arbitrary groff output into grotty is a common mistake: groff has already run the driver, so the second invocation sees terminal output instead of the intermediate format it expects.

2. Render a small document with the default terminal format

Create a disposable roff file in /tmp. This changes no installed man page and can be left for inspection or removed later with your normal file-clean-up process.

$ demo=$(mktemp /tmp/grotty-demo.XXXXXX.roff)
$ printf '%s\n' \
  '.TH DEMO 1' \
  '.SH NAME' \
  'demo - terminal output test' \
  '.PP' \
  'This is \f[B]bold\f[] and \f[I]italic\f[].' > "$demo"
$ groff -Tutf8 "$demo" | sed -n '1p' | sed -n l
demo ... This is \033[1mbold \033[22mand \033[4mitalic\033[24m.$

The exact text includes terminal escape bytes, so the escaped display from sed -n l is useful evidence. A real terminal normally interprets the SGR sequences as bold and underlined italic text. With the UTF-8 device, drawing characters and Unicode text are also available where the input and font descriptions support them.

3. Keep terminal attributes when using less

A pager must be told to pass SGR sequences through. GNU less uses -R for this purpose. The option is particularly relevant when viewing a saved rendering rather than invoking man, whose configuration may already select a suitable pager.

$ groff -Tutf8 "$demo" | less -R

Scroll through the document and quit with q. If you see literal escape notation, the pager was not configured to pass the sequences. If colours or links are still absent, check the terminal emulator as well as less. OSC 8 hyperlinks require a pager and terminal that support them; they are not guaranteed merely because grotty emitted them.

4. Select italic or reverse-video rendering

By default, grotty represents oblique text with underlining because italic terminal support is historically uneven. Pass driver options through groff with -P. On this installation, -P -i produces SGR italic output.

$ groff -Tutf8 -P -i "$demo" | sed -n '1p' | sed -n l
demo ... \033[3mitalic\033[23m.$

The alternative -P -r asks for reverse video for oblique text. It is ignored if -i or legacy mode is also selected. These choices affect presentation only; they do not change the roff source.

5. Use legacy output for limited terminals

The -c option suppresses SGR and OSC sequences. Instead, bold is represented by printing a character, a backspace, and the character again; italics use an underscore and backspace. This is useful for old paper-terminal conventions and simple consumers that cannot interpret ANSI control sequences.

$ troff -Tutf8 "$demo" | grotty -c | sed -n '1p' | sed -n l
demo ... This is b\bbo\bol\bld\bd and _\bi_\bt_\ba_\bl_\bi_\bc.$

Use troff here because it produces the intermediate output that grotty consumes. Do not replace this with groff ... | grotty -c; that fails with a message such as the first command must be 'x T'. To make legacy mode the default for a process, set GROFF_NO_SGR in its environment, or use -P -c when calling groff.

$ GROFF_NO_SGR=1 groff -Tutf8 "$demo" | sed -n '1p' | sed -n l

Legacy output is not a safety filter. It still represents document content, and it can still contain characters that a terminal treats specially. Use it to solve a compatibility problem, not as a general-purpose sanitiser.

6. Disable drawing when line art causes trouble

For UTF-8 output, simple horizontal and vertical \D drawing commands become Unicode box-drawing characters. Other devices use characters such as -, | and +. If a document's line art is confusing or a downstream text consumer needs plain text, pass -d to ignore all drawing commands.

$ groff -Tutf8 -P -d "$demo" > /tmp/demo-plain.txt
$ sed -n '1,4p' /tmp/demo-plain.txt

This only changes the rendering. It does not edit the source document. Remove the temporary output when it is no longer useful, and take care not to overwrite a file you need: redirecting with > truncates an existing destination before the command runs.

7. Diagnose the usual failure modes

• Missing formatting: inspect the first line with sed -n l. SGR bytes prove that grotty emitted attributes; literal bytes in the terminal point to the pager or emulator.
• Driver rejects input: check whether a previous groff command already ran grotty. Use troff -Tutf8 file | grotty -c for a direct driver test.
• Italic text is underlined: that is the normal default. Use groff -Tutf8 -P -i file if the terminal supports SGR italics.
• Broken diagrams: try -P -d. The driver is intended for simple documents and does not support fractional movement or arbitrary drawing shapes.
• Unexpected font or device files: inspect GROFF_FONT_PATH and any -F option. A custom directory takes precedence in the search path and can change the selected descriptions.