groff

Format output for a PostScript printer, saving the output to a file

$ groff [path/to/input.roff] > [path/to/output.ps]

$ groff -man -T ascii [path/to/manpage.1] | less --RAW-CONTROL-CHARS

$ groff -man -T html [path/to/manpage.1] > [path/to/manpage.html]

$ groff [-t] [-p] -[me] -T [pdf] [path/to/input.me] > [path/to/output.pdf]

$ eval "$(grog -T utf8 [path/to/input.me])"

groff [option...] [file...]

-e
    Preprocess the input with eqn for typesetting mathematical equations.

-p
    Preprocess the input with pic for drawing diagrams.

-t
    Preprocess the input with tbl for formatting tables.

-s
    Preprocess the input with soelim for handling `.so` requests (source inclusion).

-R
    Preprocess the input with refer for processing bibliographic references.

-z
    Preprocess the input with grap for drawing graphs.

-Tdev
    Specify the output device. Common devices include ps (PostScript), pdf, html, ascii (plain text), and dvi.

-mname
    Select a macro package to use (e.g., man for manual pages, ms for manuscripts, mm for memoranda).

-opages
    Output only the specified pages. Pages can be listed as ranges or individual numbers (e.g., `1-5`, `7`, `9-`).

-Ipath
    Add path to the search path for include files (specified by `.so` requests).

-Lpath
    Add path to the search path for macro files.

-Parg
    Pass arg directly to the postprocessor, which renders the output for the specified device.

-U
    Enable "unsafe" mode, allowing `groff` to use `open` and `exec` requests, which can pose security risks.

-V
    Display version information and exit.

-v
    Display a shorter version string and exit.

-Wwarning
    Disable specific warnings (e.g., `Wwarn-all` for all warnings, `Wno-macro` for macro warnings).

-wwarning
    Enable specific warnings (e.g., `wall` for all warnings, `wmacro` for macro warnings).

groff is a powerful and versatile document formatting system, a free implementation of the classic troff typesetting program. It takes plain text files embedded with `roff` formatting requests and macro calls, processing them to produce high-quality output for various devices.

Originally developed for Unix, groff extends and enhances the functionality of its predecessors, troff and nroff. It is widely used in the Linux and Unix world, most notably for rendering man pages, but also for creating books, technical documentation, and reports.

The system's strength lies in its modularity and extensibility. It utilizes specialized preprocessors like eqn for equations, pic for diagrams, tbl for tables, and refer for bibliographies, allowing complex content to be embedded directly within the source document. Furthermore, groff supports various macro packages (e.g., man, ms, mm) that provide higher-level formatting commands, simplifying document creation.

Output can be generated in multiple formats, including PostScript, PDF, HTML, DVI, and plain text, making groff a flexible tool for a wide range of publishing needs. Despite its age, groff remains a fundamental component of many Unix-like operating systems.

Learning groff can be challenging due to its complex and often arcane syntax, which is rooted in its troff heritage. While extremely powerful for precise typesetting, modern users might find alternatives like Markdown or LaTeX easier for general document preparation. Its primary and most widespread use today is for formatting man pages, where its deep integration with the Unix ecosystem remains essential.

Groff leverages a suite of specialized preprocessors to handle different types of content before the main troff formatter processes the document. Each preprocessor interprets its own markup language for a specific task. For example, eqn processes mathematical equations, pic draws diagrams, tbl formats tables, and refer manages bibliographic references. These tools allow complex, structured content to be seamlessly integrated into `roff` source files.

Macro packages in groff provide a higher-level abstraction over the basic `roff` commands, simplifying document creation. Instead of writing low-level formatting requests, users employ macros that represent common document structures (e.g., headings, paragraphs, lists). Popular packages include man (for manual pages), ms (for manuscripts), and mm (for memoranda). Selecting a macro package with the `-m` option significantly streamlines the document writing process.

Groff is designed to produce output suitable for a variety of devices or formats, specified using the `-T` option. Common output devices include ps (PostScript), pdf (Portable Document Format), html (HyperText Markup Language), ascii (plain text), and dvi (Device Independent file format, often used with TeX systems). This versatility allows groff documents to be viewed, printed, or published in many contexts.

Groff (GNU troff) is the GNU project's free software implementation of the troff and nroff text formatters, which originated in Bell Labs. Development of groff was started by James Clark in 1990, with the goal of creating a fully compatible replacement for the proprietary troff.

Since its inception, groff has become the standard typesetting system for most Unix-like operating systems, notably Linux. Its development has focused on maintaining compatibility with legacy troff documents and providing extensibility through modern features and support for various output formats. It has been crucial for the widespread adoption and consistent display of man pages across diverse systems.

troff(1), nroff(1), man(1), eqn(1), pic(1), tbl(1), refer(1), roff(7)