roff2text

roff2text [ -a groff-options ] [ -m macro-set ] [ -w width ] [ -t tab-width ] [ -R ] [ file... ]

-m name
    Specify a macro set (e.g., 'mandoc') to be used by groff during conversion. This option is passed directly to the underlying groff command, enabling support for specific document types.

-w width
    Set the maximum output line width for the plain text. This controls how lines are wrapped in the final output, ensuring readability within a specified column limit.

-t tab-width
    Define the width of tab stops in the output. This affects how tab characters within the roff source are expanded in the plain text.

-R
    Output raw groff text without further post-processing (e.g., without piping through col -b). This can be useful for debugging or when the output needs to be processed by another utility.

-a groff-options
    Pass additional arbitrary options directly to the underlying groff command. This provides advanced users with fine-grained control over the groff rendering process.

file...
    One or more input roff/groff files to be converted. If no files are specified, roff2text reads its input from standard input (stdin).

roff2text is a utility designed for converting documents written in the roff or groff markup languages into a clean, readable plain text format. It acts as a convenient front-end to the more powerful groff typesetting system, simplifying the conversion process for common use cases. Primarily optimized for converting man pages and other roff-formatted documents, it renders the content to standard output, effectively stripping most formatting codes and presenting a text version suitable for display on a terminal, for logging, or for further text processing. The command intelligently handles character encodings and line wrapping, aiming to produce a clear and legible output.

roff2text relies on the groff typesetting system, which must be installed and properly configured on your system. While it aims to accurately convert roff documents to plain text, some complex formatting elements, such as intricate tables, mathematical equations, or highly graphical constructs, might not translate perfectly and could appear malformed or be omitted in the plain text output. It is best suited for documents primarily designed for text-based display, such as man pages, rather than complex typeset documents.

roff2text reads its input from the specified file arguments. If no files are provided on the command line, it gracefully accepts input from standard input (stdin), making it highly suitable for use in shell pipelines (e.g., `zcat manpage.gz | roff2text`). The resulting plain text output is consistently written to standard output (stdout), which allows for easy redirection to a file or piping the output to subsequent commands for further processing, such as `roff2text file.man > output.txt`.

The command functions by internally invoking the groff typesetting engine with a specific set of options tailored for plain text output. For instance, it often uses `groff -Tlatin1` or `groff -Tutf8` for character encoding and then pipes the intermediate output through utilities like col -b to handle backspaces and tabs, which are common in roff processing, ensuring the final text is clean and readable on a terminal without extraneous control characters. This makes it a robust wrapper for common text conversion tasks.

roff2text is an integral component of the GNU groff (GNU roff) project, which is a free software reimplementation of the classic Unix troff and nroff text formatting systems. Its development emerged from the need for a modern, open-source text formatter compatible with traditional Unix roff utilities. As a dedicated front-end, roff2text leverages groff's robust parsing and rendering capabilities to provide a straightforward way to extract plain text from roff sources, particularly useful for displaying man pages in a terminal or for programmatic access to their content. It has been a standard part of the groff distribution for many years.

groff(1), troff(1), nroff(1), man(1)