How to Use the Command 'groff' (with Examples)

Groff is a typesetting system that serves as the GNU replacement for the historical troff and nroff utilities. It is a powerful tool for formatting documents written in the roff format, enabling users to produce high-quality printed output. Groff is particularly valuable for its ability to handle a variety of text formatting tasks, from document headers and footers to sophisticated tables and picture integration. While it can output documents in PostScript, PDF, ASCII, and HTML, Groff also supports many different macro packages for specific formatting needs. Below are specific examples of how to utilize Groff for various typesetting tasks.

Use case 1: Format output for a PostScript printer, saving the output to a file

Code:

groff path/to/input.roff > path/to/output.ps

Motivation:

Using a text formatter like Groff can dramatically improve the appearance and layout of a document, especially when dealing with roff-formatted input files. The PostScript format is widely accepted for printers and publishing, providing high-quality output. This use case caters to users who need to generate precise print-ready files for professional or personal projects from raw typesetting code.

Explanation:

• groff: Invokes the Groff system to process a document.
• path/to/input.roff: Specifies the path to the input file in roff format that needs to be processed.
• >: Redirects the output to a specific file.
• path/to/output.ps: Determines the destination file, in this case, with a .ps extension, indicating a PostScript output.

Example Output:

The result is a PostScript file, output.ps, with beautifully formatted pages ready for review or printing, displaying all the text, tables, and images as intended from the original roff document.

Use case 2: Render a man page using the ASCII output device, and display it using a pager

Code:

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

Motivation:

Unix and Linux man pages are vital resources for learning how various commands work. Viewing them in a pager like less allows for easy navigation through potentially lengthy documents. This use case is significant for users who need to access and read man pages on systems that may not display them in a terminal’s default mode.

Explanation:

• groff: Launches the Groff system.
• -man: Specifies the use of the man macro package to format the document as a manual page.
• -T ascii: Sets the output format to ASCII text, suitable for terminals or text viewers.
• path/to/manpage.1: Indicates the input file, in this case, a man page with a .1 extension.
• |: Pipes the command output to another program.
• less --RAW-CONTROL-CHARS: Opens the processed document in a pager that can handle control sequences for character formatting.

Example Output:

An easily navigable depiction of a man page in plain ASCII, as displayed in the terminal using less. Though devoid of stylized fonts or colors, it retains the essential structure and readability of the document.

Use case 3: Render a man page into an HTML file

Code:

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

Motivation:

Converting man pages to HTML is useful for web access and distribution. This format is universally accessible due to web browsers, making a man page’s information available to those who prefer or require a graphical interface. It’s beneficial for documentation purposes, as HTML files can easily be shared or linked on websites.

Explanation:

• groff: Initiates Groff.
• -man: Applies the man macro package to format the content as a manual.
• -T html: Transforms the output into HTML format.
• path/to/manpage.1: References the source man page file.
• >: Directs the output to a designated file.
• path/to/manpage.html: Denotes the output file in HTML format.

Example Output:

An HTML file, manpage.html, that replicates the structure and content of the original man page but in a web-friendly format, complete with headers, text content, and navigable links if applicable.

Use case 4: Typeset a roff file containing [t]ables and [p]ictures, using the [me] macro set, to PDF, saving the output

Code:

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

Motivation:

Combining text with tables and pictures creates a compelling and informative document. Transforming such complex roff files using the me macro set into PDF extends its use for digital documentation that is broadly compatible and can be shared effortlessly. This is particularly important for reports or publications that require precise formatting and visual elements.

Explanation:

• groff: Executes the Groff system.
• -t: Engages tbl, the table preprocessor, to process any tables in the document.
• -p: Uses pic, the picture preprocessor, to integrate and format illustrations.
• -me: Invokes the me macro set, known for processing documents that demand scientific and technical objectives.
• -T pdf: Specifies the output format as PDF, popular for document sharing and printing.
• path/to/input.me: Represents the input file in the roff format with applied macros.
• >: Directs the processed output to a specific location.
• path/to/output.pdf: Indicates the resulting file in PDF format.

Example Output:

A polished, professional-quality PDF document, output.pdf, that incorporates sophisticated formatting features such as tables and pictures, meticulously arranged according to the specifications in the original roff source file.

Use case 5: Run a groff command with preprocessor and macro options guessed by the grog utility

Code:

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

Motivation:

Handling a roff file without knowing its specific combination of preprocessors and macros can be cumbersome. The grog utility simplifies this by analyzing the file and suggesting an optimal Groff command. This is invaluable for users dealing with unfamiliar roff documents, ensuring correct processing without manual trial and error.

Explanation:

• grog: A utility that intelligently guesses the necessary Groff command options for a given input file.
• -T utf8: Specifies the desired output encoding as UTF-8.
• path/to/input.me: Points to the input file in roff format.
• eval "$( ... )": Executes the generated command directly in the shell, applying the appropriate Groff options determined by grog.

Example Output:

The execution of a dynamically constructed Groff command that correctly preprocesses and formats the document, outputting it in the UTF-8 encoding. This ensures broad compatibility with text editors and viewers.

Conclusion:

The Groff typesetting system is a multifaceted tool essential for text processing and formatting in professional environments. From generating polished PostScript and PDF outputs to converting documents into web-friendly HTML, Groff’s versatility is unrivaled. The provided use cases demonstrate its range, offering solutions to both simple typesetting tasks and complex document processing challenges. Whether for printing, digital sharing, or efficient man-page viewing, Groff remains a crucial utility in the toolbox of any user dealing with textual documents in the Unix ecosystem.