Preview nroff Output Safely with colcrt

You will turn formatted nroff output into readable plain terminal text, with sensible handling for terminals that cannot display half-line motion or destructive overstriking. The guide uses the installed colcrt from bsdextrautils, which reports util-linux 2.41.3 on this machine. Allow about ten minutes for a first test. You do not need root for any command here.

1. Check the installed command

Start by confirming that the executable and its option set are the ones you expect. The package version is useful when comparing 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

Checkpoint: the command is available, and you know which package supplied it. If command -v prints nothing, stop and install or repair the package through your normal system-management process. Do not copy a binary from another host just to make a preview work.

2. Preview a formatted document

colcrt reads files named on the command line, or standard input when no files are given. In the usual workflow, a formatter such as nroff produces terminal control sequences and colcrt makes the result suitable for a limited terminal.

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

Replace the path with a real input file. This pipeline writes the preview to standard output, so it does not alter the roff source. If the document does not use tbl tables, the first stage may not be necessary. The formatter and macro package are separate from colcrt; a missing nroff or an unsuitable macro option is not a colcrt failure.

For a direct 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

Checkpoint: ordinary text survives unchanged. If a pipeline produces no useful text, run each stage separately and inspect its output. This keeps a formatter problem from being mistaken for a terminal-filter problem.

3. Choose how underlining is shown

The normal output keeps underlining by placing a dash on a separate line. That is useful when a CRT preview should show 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 while previewing boxed tables created by tbl. It suppresses all underlining; it does not remove ordinary hyphens that were printed as document content.

Checkpoint: choose the output mode before redirecting a long preview. If you need both forms, run the pipeline twice and write to two new destinations rather than overwriting a useful capture.

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, effectively double-spacing the result. This is useful when superscripts or subscripts would otherwise become partly invisible, and can also suit output intended for a line printer.

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

Expect more vertical space with this option. It is not a general quality setting and it does not reconstruct every formatting feature. Compare both modes against the original document when a superscript, subscript or table boundary carries meaning.

Checkpoint: use normal mode for a compact terminal preview, and -2 when vertical positioning is more important than compactness. If the input was already double-spaced, the manual warns that the result can still need special handling.

5. Save a preview without destroying an old one

Shell redirection is safe for the source but not automatically safe for an existing output file. The > operator truncates its destination before the pipeline finishes. Use 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. Inspect 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

That removal is irreversible for the temporary file. It does not touch the source document or an existing preview.txt. Avoid sudo: if you cannot write 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. General overstriking is lost. The manual gives a special case where a vertical bar overstruck with a dash or underline becomes a plus sign. Lines are trimmed to 132 characters, and the implementation cannot back up more than 102 lines. Treat the result as a terminal preview rather than a source for publication or round-trip conversion.

Underlines are changed to dashes on separate lines, and half-line characters are also placed on intervening lines. If alignment is wrong, first check the formatter, macro package and selected colcrt mode. 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

These commands do not read or modify 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