Back to Commands

troff

text processinglinux
The troff command is one of the most frequently used commands in Linux/Unix-like operating systems. troff The troff command (typesetter roff) is a document formatting system for Unix-like operating systems that formats text for typesetter and printing devices. It's the foundation of the groff formatting system and provides detailed control over document typography and layout.
See ExamplesView Syntax

Quick Reference

Command Name:

troff

Category:

text processing

Platform:

linux

Basic Usage:

troff [options] [arguments]

Common Use Cases

  • 1

    Document formatting

    Create formatted documents using the troff typesetting system

  • 2

    Report generation

    Generate professional-quality reports and documents

  • 3

    Scripting

    Use in shell scripts to generate formatted documents programmatically

  • 4

    Document processing

    Manipulate and transform document data

Syntax

troff [OPTION]... [FILE]...

Options

Option Description
-a Produce ASCII output instead of device-specific code
-b Print a backtrace with each warning or error
-c Disable color output
-C Enable compatibility mode
-d CS Define a string CS for use in the document
-e Preprocess with eqn (for mathematical equations)
-E Inhibit error messages
-f F Use file F instead of the standard font directory
-F DIR Search directory DIR for device description files
-i Read standard input after all files
-I DIR Search directory DIR for files included with .so requests
-m NAME Use macro file NAME (e.g., -ms, -man, -mm, -mom)
-M DIR Search directory DIR for macro files
-n N Number first page N
-o LIST Output only pages in LIST
-p Preprocess with pic (for diagrams)
-P OPTION Pass OPTION to the postprocessor
-r CN Set register C to the value N
-R Preprocess with refer (for bibliographic references)
-s Preprocess with soelim (for file inclusion)
-S Safer mode (disable some potentially unsafe features)
-t Preprocess with tbl (for tables)
-T DEV Prepare output for device DEV (ps, pdf, html, etc.)
-U Unsafe mode (enable potentially dangerous operations)
-v Print version information
-V Print detailed version information
-w Enable warning messages
-W LEVEL Set warning level to LEVEL
-z Suppress formatted output (useful for checking syntax)

Examples

How to Use These Examples

The examples below show common ways to use the troff command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

Basic Examples:

troff -ms document.ms | dpost | lpr

Format a document using ms macros, convert to PostScript with dpost, and send to the printer. This traditional workflow was common for printing formatted documents.

troff -man manual.1 | dpost > manual.ps

Format a man page and convert it to PostScript. This creates a high-quality, typeset version of a manual page suitable for printing.

troff -ms -Tpdf document.ms > document.pdf

Format a document with ms macros directly to PDF. Modern implementations like groff can output to various formats including PDF.

troff -t -e -ms technical.ms | dpost > technical.ps

Format a technical document with tables and equations to PostScript. The -t and -e options enable the tbl (table) and eqn (equation) preprocessors.

Advanced Examples:

troff -t -p -e -ms -rN2 document.ms | dpost > document.ps

Format a document with tables, pictures, and equations, starting page numbering from 2. This demonstrates combining multiple preprocessors and setting register values.

troff -mom document.mom | dpost > document.ps

Format a document using the mom (my own macros) package and output to PostScript. The mom macros offer a more accessible interface to troff's capabilities.

pic document.pic | tbl | eqn | troff -ms | dpost > document.ps

Process a document through multiple preprocessors in sequence. This pipeline processes diagrams, tables, and equations before formatting the text with troff.

echo ".sp 2\n.ce\nHello, World!\n.sp 2" | troff | dpost > hello.ps

Format a simple troff markup provided directly as input. This creates a centered "Hello, World!" with space above and below, demonstrating basic troff formatting commands.

troff -ms -rCL6i document.ms | dpost > custom_length.ps

Format a document with a custom page length. The -rCL6i option sets the page length to 6 inches, creating a shorter page than the default.

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

What Troff Does:

  • Formats text for typesetting and high-quality printing devices
  • Provides precise control over typography, layout, and document structure
  • Processes marked-up text files containing formatting commands
  • Outputs device-specific code that is processed by a postprocessor
  • Serves as the foundation for document formatting systems on Unix/Linux
  • Supports various macro packages for different document types

History and Context:

  • troff stands for "typesetter runoff" and was developed at Bell Labs in the 1970s
  • It evolved from the earlier "roff" program created by Joe Ossanna
  • Brian Kernighan extended the system, adding many capabilities
  • The GNU version, groff, is the most widely used implementation today
  • Despite its age, troff remains important for Unix documentation
  • The man page system is based on troff with the "man" macro package

Common Use Cases:

  • Creating professional typeset documents with precise control
  • Producing man pages for Unix/Linux systems
  • Formatting technical papers and articles with complex requirements
  • Generating camera-ready documents for publication
  • Creating documents with consistent typography across different outputs
  • Producing books with chapters, sections, and complex design elements

Macro Packages:

  • man: For creating Unix manual pages (-man)
  • ms: General-purpose macros for articles and papers (-ms)
  • mm: Memorandum macros for business documents (-mm)
  • mom: A more modern, user-friendly macro set (-mom)
  • me: Macros for papers and theses (-me)
  • mdoc: Semantic macros for BSD documentation (-mdoc)

Preprocessors:

  • tbl: For creating tables (-t)
  • eqn: For mathematical equations and formulas (-e)
  • pic: For line drawings and diagrams (-p)
  • refer: For bibliographic references (-R)
  • soelim: For including external files (-s)
  • chem: For chemical structure diagrams
  • grap: For graphs and charts

Troff vs. Nroff:

  • troff produces output for typesetters and high-resolution devices
  • nroff produces text output for terminals and line printers
  • Both process the same input files but generate different output
  • troff offers more sophisticated formatting capabilities
  • In modern systems, both are typically implemented as front-ends to groff

Related Commands:

  • groff - GNU version of troff with enhanced capabilities
  • nroff - Formatter for terminal display and line printers
  • dpost - PostScript postprocessor for troff output
  • tbl - Table preprocessor for troff/nroff
  • eqn - Equation preprocessor for troff/nroff
  • pic - Picture preprocessor for troff/nroff
  • man - Interface to the online reference manuals

Tips & Tricks

1

Use the -T device option to specify the output device

2

Use the -m device option to specify the input device

3

Use the -r resolution option to specify the resolution

4

Use the -p paper option to specify the paper size

5

Use the -h option to display help

Common Use Cases

Document formatting

Create formatted documents using the troff typesetting system

Report generation

Generate professional-quality reports and documents

Scripting

Use in shell scripts to generate formatted documents programmatically

Document processing

Manipulate and transform document data

Typesetting

Create high-quality typeset documents

Related Commands

These commands are frequently used alongside troff or serve similar purposes:

Explore All Commands

Use Cases

1

Document formatting

Create formatted documents using the troff typesetting system

2

Report generation

Generate professional-quality reports and documents

3

Scripting

Use in shell scripts to generate formatted documents programmatically

4

Document processing

Manipulate and transform document data

5

Typesetting

Create high-quality typeset documents

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the troff command works in different scenarios.

See ExamplesTry Lab Exercises
$ troff
View All Commands