Preview and Diagnose roff Documents with troff

You will use the installed GNU troff to turn a small roff document into a plain-text preview, inspect warnings without producing formatted output, and select pages for a device-independent output stream. The examples use GNU troff 1.23.0 from the groff-base package, version 1.23.0-3build2 on this machine.

Allow about fifteen minutes. You need a shell and a roff input file. No elevated privileges are needed. The examples only read input and write files in the current directory when you explicitly redirect output.

1. Check the installed command

Start by checking the binary and its version. This is a read-only checkpoint:

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

troff is the formatter at the centre of the roff system. It reads roff requests, macros and ordinary text, then emits device-independent output. It does not normally produce a terminal-friendly document. The groff command is the usual front end when you also need preprocessors and an output driver.

2. Make a minimal input file

Use a temporary example first, so you can compare each mode without risking a real document. The .TH, .SH and .PP requests are common man-page macros, but they are only useful when the corresponding macro package is loaded:

$ cat > sample.roff <<'EOF'
.TH SAMPLE 1
.SH NAME
sample \- a small test
.SH DESCRIPTION
.PP
This is a short sentence for troff.
EOF

The here-document creates a file and replaces any existing sample.roff in the current directory. If that name matters, stop before running it or choose a new name. To remove this test file later, use rm -- sample.roff only after checking the path with pwd and ls -l -- sample.roff.

3. Produce a readable preview

Pass -a to generate a plain-text approximation rather than the normal device-independent stream:

$ troff -a sample.roff
<beginning of page>
sample <-> a small test This is a short sentence for troff.

This is a diagnostic preview, not a typeset replacement. Page breaks are marked with angle-bracket text, horizontal movement is approximated with spaces, and vertical movement is omitted. The manual explicitly treats the details of this output as subject to change, so use it to inspect content and rough line breaking, not as a stable interchange format.

Checkpoint: if the preview is empty or unexpectedly short, check that you passed the intended file and that its macro package is available. Run sed -n '1,40p' sample.roff and repeat the command. A missing file is an input error, not a reason to add sudo.

4. Understand the normal output

Without -a, troff writes device-independent output to standard output. It is control data for a device driver, so do not judge success by opening it in a terminal:

$ troff sample.roff > sample.out
$ wc -c sample.out
268 sample.out

The byte count depends on the input and device descriptions, but this sample produces 268 bytes with GNU troff 1.23.0. The useful check is that the command completed successfully and produced a non-empty output file. If you want a human-readable terminal result, use the front end and select an ASCII device:

$ groff -Tascii sample.roff | sed -n '1,12p'
sample - a small test This is a short sentence for troff.

That distinction prevents a common distraction: -Tascii changes the output device, but calling troff directly still leaves you with device output. groff adds the driver step that makes an ASCII terminal result useful.

5. Inspect errors and warnings safely

Use -z when you want diagnostics but do not want formatted output. It suppresses the output stream; it does not suppress messages produced by the document or macro package:

$ troff -z sample.roff > /tmp/sample.troff.out
$ wc -c /tmp/sample.troff.out
0

Warnings are grouped by category. For example, enable missing-argument warnings with -w missing, or file warnings with -w file. Use -W to inhibit a category. A warning is evidence to investigate, not proof that formatting stopped. Capture standard error separately when testing a script:

$ troff -z -w missing sample.roff >/tmp/sample.troff.out 2>/tmp/sample.troff.err
$ printf 'status: %s, output bytes: ' "$?"
status: 0, output bytes: 0
$ sed -n '1,20p' /tmp/sample.troff.err

Keep the exit status check immediately after troff. Running sed first would replace the status you are trying to record.

6. Limit processing to selected pages

Use -o with a comma-separated page list when a large document only needs a subset. A single number selects one page; a range selects every page in the inclusive range:

$ troff -o 1 sample.roff > first-page.out
$ troff -o 2-4 report.roff > pages-two-to-four.out

troff stops after the last page listed. The page list is about formatted page numbers, not input line numbers. If your document changes its page numbering with -n or roff requests, confirm the result against the document rather than assuming the first input section is page 1.

7. Keep unsafe mode out of normal workflows

GNU troff disables several requests by default because they can open or write arbitrary files, run commands or send input to another process. The -U option enables unsafe mode, including requests such as open, pi, pso and sy. Do not add -U to make an unfamiliar document "work". Treat roff input from another person or system as untrusted data and inspect it first.

That warning matters even when the document looks like ordinary text: requests can be hidden in macros or included files. If a trusted build genuinely requires an unsafe request, isolate the build, use a dedicated working directory and review the input and every included file. There is no undo command for a command that an unsafe document has already run.