Back to Commands

groff

text processinglinux
The groff command is one of the most frequently used commands in Linux/Unix-like operating systems. groff The groff command (GNU troff) is a document formatting system that converts marked-up text files to formatted documents for display or printing. It's used for creating man pages, technical documentation, and other formatted documents with precise typographical control.
See ExamplesView Syntax

Quick Reference

Command Name:

groff

Category:

text processing

Platform:

linux

Basic Usage:

groff [options] [arguments]

Common Use Cases

  • 1

    Document formatting

    Create formatted documents using the groff 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

groff [OPTION]... [FILE]...

Options

Option Description
-a Generate an ASCII approximation of the typeset output
-b Print a backtrace with each warning or error message
-c Disable color output
-e Preprocess with eqn (for equations and mathematical notation)
-E Inhibit all error messages of troff and its preprocessors
-g Preprocess with grn (for gremlin illustrations)
-G Process with grap preprocessor (for graphs)
-i Read standard input after all specified files
-I DIR Search directory DIR for included files
-j Preprocess with chem (for chemical structure diagrams)
-J Preprocess with refer (for bibliographic references)
-k Produce output that maintains the original page layout
-l Send the output to a printer
-m PACKAGE Use macro package PACKAGE (e.g., -man, -ms, -mm, -mom)
-M DIR Search directory DIR for macro files
-n NUM Number first page NUM
-N Disable groff extensions (for compatibility with classical troff)
-p Preprocess with pic (for diagrams)
-P ARG Pass ARG to the postprocessor
-r REG=VAL Set register REG to VAL
-R Preprocess with refer and process citations
-s Preprocess with soelim (for including files)
-S Safer mode (disable some potentially unsafe features)
-t Preprocess with tbl (for tables)
-T FORMAT Set output format to FORMAT (e.g., -Tpdf, -Thtml, -Tps, -Tascii)
-v Print version information
-w Enable warning messages
-W LEVEL Set warning level to LEVEL
-z Suppress formatted output (for checking errors)

Examples

How to Use These Examples

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

Basic Examples:

groff -man manpage.1

Format a man page file (manpage.1) for terminal display. This processes the file with the "man" macro package, which is designed for creating Unix manual pages.

groff -man -Tpdf manpage.1 > manpage.pdf

Format a man page file and output as PDF. The -T option specifies the output format (in this case, PDF), allowing you to create professional-looking documentation.

groff -ms document.ms -T html > document.html

Format a document using the ms macros and output as HTML. The ms macro package is useful for general document formatting, and the HTML output can be viewed in any web browser.

groff -t -e -mandoc -Tascii manpage.1 | less

Format a man page with tbl and eqn preprocessors for ASCII output and view with less. The -t and -e options enable the tbl (table) and eqn (equation) preprocessors for handling tables and mathematical equations.

Advanced Examples:

groff -pet -ms complex.ms -Tps > complex.ps

Process a document with pic, eqn, and tbl preprocessors, using ms macros, and output as PostScript. This combines multiple preprocessors for handling diagrams (-p), equations (-e), and tables (-t) in a single document.

man ls | groff -man -Thtml > ls.html

Convert a man page directly from the man command to HTML format. This is useful for creating web-readable versions of man pages from the system's documentation.

groff -mom document.mom -Tps > document.ps

Format a document using the mom (my own macros) package with PostScript output. The mom macro package provides a more user-friendly interface to groff with many features for creating complex documents.

echo ".TL\nHello World\n.PP\nThis is a test." | groff -ms -Tutf8

Format a simple document provided directly as input with ms macros and output in UTF-8. This demonstrates how groff can process text input directly from the command line for quick formatting tasks.

groff -k -man -Tps manpage.1 > manpage.ps

Process a man page with the "man" macro package, maintaining the original page layout, and output as PostScript. The -k option preserves page layout information, which can be important for documents with complex formatting.

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 Groff Does:

  • Processes marked-up text files to create formatted documents
  • Offers precise control over typesetting and document layout
  • Supports various output formats including PostScript, PDF, HTML, and plain text
  • Includes multiple preprocessors for specialized content like tables, equations, and diagrams
  • Provides several macro packages for different document types (man pages, articles, books)
  • Serves as the formatting system behind the man command for Unix manual pages

Common Use Cases:

  • Creating and formatting man pages for Unix/Linux documentation
  • Producing technical documentation with complex formatting requirements
  • Generating papers and articles with precise typographical control
  • Converting documents to multiple output formats from a single source
  • Creating books with chapters, sections, tables of contents, and indexes
  • Formatting documents with complex elements like tables, equations, and diagrams

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: My Own Macros, a more user-friendly package with many features (-mom)
  • me: Eric Allman's 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)
  • grap: For graphs and charts (-G)
  • chem: For chemical structure diagrams (-j)

Output Formats:

  • ps: PostScript output (-Tps)
  • pdf: PDF output (-Tpdf)
  • html: HTML output (-Thtml)
  • ascii: Plain text output for terminals (-Tascii)
  • utf8: UTF-8 text output for terminals (-Tutf8)
  • dvi: Device Independent format for TeX (-Tdvi)
  • X*: Various X11 device drivers

Related Commands:

  • troff - The basic typesetting program (groff is GNU's enhanced version)
  • nroff - For formatting to character devices (included in groff)
  • man - The system's manual page viewer (uses groff/nroff)
  • tbl - Table preprocessor (used with groff -t)
  • eqn - Equation preprocessor (used with groff -e)
  • pic - Picture/diagram preprocessor (used with groff -p)
  • gzip -d - Often needed to uncompress man pages before processing

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 groff 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 groff or serve similar purposes:

Explore All Commands

Use Cases

1

Document formatting

Create formatted documents using the groff 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 groff command works in different scenarios.

See ExamplesTry Lab Exercises
$ groff
View All Commands