Preview nroff Output Safely with colcrt

Some terminals cannot show half-line motion, and overstriking makes a formatted page look like it was typed by a cat. colcrt turns formatted nroff output into readable text for a limited terminal. The guide uses the installed colcrt from bsdextrautils, which reports util-linux 2.41.3 on this machine. Allow about ten minutes, and note that no command here needs root.

1. Check the installed command

Confirm that the executable is the one you expect. The package version is worth noting when you compare output between machines, because formatting details belong to the installed util-linux release.

$ command -v colcrt
/usr/bin/colcrt
$ dpkg-query -W -f='${Package} ${Version}\n' bsdextrautils
bsdextrautils 2.39.3-9ubuntu6.6
$ colcrt --version
colcrt from util-linux 2.41.3

2. Preview a formatted document

colcrt reads the files named on the command line, or standard input when there are none. The usual workflow has a formatter such as nroff produce the terminal control sequences, and colcrt make them fit a limited terminal.

$ tbl /path/to/document.roff | nroff -ms | colcrt

Replace the path with a real input file. The pipeline writes the preview to standard output, so the roff source is not altered. If the document has no tbl tables, you can drop the first stage. The formatter and macro package are separate from colcrt: a missing nroff or an unsuitable macro option is not a colcrt failure.

For a smoke test that needs no document, send two ordinary lines through standard input:

$ printf '%s\n' 'first line' 'second line' | colcrt
first line
second line

3. Choose how underlining is shown

By default the output keeps underlining by putting a dash on a separate line. That shows a CRT preview that text was marked, but it can make tables harder to read. A lone dash is not necessarily content from the source document.

$ printf 'A\b_\n' | colcrt
A
 -
$ printf 'A\b_\n' | colcrt --no-underlining
A

The short spelling of --no-underlining is a single hyphen: -. Use it when the marks are visual noise, especially for boxed tables made by tbl. It suppresses all underlining, but it does not remove ordinary hyphens that were printed as document content.

4. Preserve half-lines when layout matters

By default colcrt uses a minimal-space layout and suppresses empty lines where it can. The -2 or --half-lines option prints all half-lines, which effectively double-spaces the result. It helps when superscripts or subscripts would otherwise vanish, and it can suit output bound for a line printer.

$ tbl /path/to/document.roff | nroff -ms | colcrt --half-lines

Expect more vertical space. This is not a general quality setting and it does not reconstruct every formatting feature. When a superscript, subscript or table boundary carries meaning, compare both modes against the original document.

5. Save a preview without destroying an old one

Shell redirection is safe for the source but not for an existing output file. The > operator truncates its destination before the pipeline finishes. Write to a new temporary name, then replace the old preview only after checking the result.

$ tbl /path/to/document.roff | nroff -ms | colcrt > preview.txt.new
$ test -s preview.txt.new && mv -- preview.txt.new preview.txt
$ sed -n '1,24p' preview.txt

If the pipeline fails, the temporary file may be incomplete. Check its status, and remove it only when you are sure it is not useful:

$ if [ -e preview.txt.new ]; then rm -- preview.txt.new; fi

Avoid sudo here. If you cannot write to the destination, choose a directory you own or fix its permissions through your normal administrative process.

6. Recognise the output limits

colcrt is a preview filter, not a lossless renderer. Know its limits:

• Overstriking is lost. The manual gives one special case: a vertical bar overstruck with a dash or underline becomes a plus sign.
• Lines are trimmed to 132 characters.
• It cannot back up more than 102 lines.
• Underlines become dashes on separate lines, and half-line characters are also placed on intervening lines.

Treat the result as a terminal preview, not a source for publication or round-trip conversion. If alignment looks wrong, check the formatter, macro package and selected colcrt mode first. Do not try to repair the source by copying visible spaces from the preview.

For diagnostics, ask the program for its own usage text and version:

$ colcrt --help
$ colcrt --version

Neither command reads or modifies input files. If a file cannot be opened, check the path and permissions without changing anything:

$ test -r /path/to/document.roff && echo readable
$ ls -l -- /path/to/document.roff