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

The troff command is part of the GNU Troff (groff) document formatting system, which is a powerful typesetting processor. It is used to convert plain text documents, often written in roff language, into formatted outputs that can be printed or viewed in various formats, such as PostScript, ASCII, and PDF. The tool is a critical component in text processing and typesetting for generating complex document structures with professional quality.

Use case 1: Format Output for a PostScript Printer, Saving the Output to a File

Code:

troff path/to/input.roff | grops > path/to/output.ps

Motivation:

When you need to print a document using a PostScript printer or want to create a high-quality digital document in the PostScript format, using troff to generate a .ps file is ideal. PostScript is a page description language used primarily in electronic and desktop publishing. This format is particularly useful if the document will undergo further processing or needs to maintain a consistent appearance across different platforms and printers.

Explanation:

• troff: This command initiates the processing of the .roff file. It takes input text formatted in the roff programming language.
• path/to/input.roff: This argument specifies the path to the input file that contains text formatted with roff macros intended for processing.
• grops: This command filters and converts the output of troff into PostScript format, making it suitable for use with PostScript printers.
• >: This operator redirects the filtered output into a file.
• path/to/output.ps: This specifies the destination path and filename for the output PostScript file.

Example Output:

The resulting file, output.ps, is a PostScript document that can be sent directly to a PostScript printer for printing or viewed using applications that support PostScript format.

Use case 2: Format Output for a PostScript Printer Using the [me] Macro Package, Saving the Output to a File

Code:

troff -me path/to/input.roff | grops > path/to/output.ps

Motivation:

Using a macro package like me simplifies document authoring by providing predefined macros that style and format text. This is particularly useful when creating structured documents like technical notes or reports that require consistent formatting. The me macros give authors powerful tools to efficiently format sections, headers, and footers without managing these styles manually.

Explanation:

• troff -me: The -me flag specifies that the me macro package should be used. me provides a suite of macros for creating formatted documents with a consistent look and feel.
• path/to/input.roff: Specifies the input file possessing the roff source text that includes me macros.
• grops: Converts the output into PostScript format.
• >: Redirects the processed output to a designated file.
• path/to/output.ps: Determines the destination file path and name where the PostScript output is saved.

Example Output:

The output.ps file generated embeds the stylistic guidelines encoded in the me macro package, resulting in a professionally formatted PostScript document.

Use case 3: Format Output as ASCII Text Using the [man] Macro Package

Code:

troff -T ascii -man path/to/input.roff | grotty

Motivation:

ASCII formatted documents are highly useful when you need plain text outputs that are inherently portable and easy to view on any text editor. Utilizing the man macro package is beneficial when structuring text intended for manual pages or instructional content, as it provides industry-standard formatting for UNIX man pages.

Explanation:

• troff -T ascii: The -T ascii flag signals that the output target is ASCII text, ensuring the output remains in plain-text format without complex typesetting used in graphical outputs.
• -man: Specifies the use of the man macros which are conventionally used for formatting UNIX manual pages, known for their specific layout and readability.
• path/to/input.roff: Points to the input file with the necessary roff source text, formatted using man macros.
• grotty: Converts the processed output into ASCII text, suitable for terminal viewing or basic printing.

Example Output:

An ASCII text file that follows the traditional sections and styling of UNIX manual pages, viewed directly in terminals or low-resource environments with no need for specialized viewers.

Use case 4: Format Output as a PDF File, Saving the Output to a File

Code:

troff -T pdf path/to/input.roff | gropdf > path/to/output.pdf

Motivation:

PDF is a widely accepted document format that preserves the visual integrity of files across devices and software platforms. Utilizing troff to produce a PDF enables seamless distribution, both digitally and in print, while maintaining the formatting styles and document layout defined in your source text.

Explanation:

• troff -T pdf: The -T pdf flag denotes that the target format of the output is PDF, prompting troff to gear its processing towards PDF generation.
• path/to/input.roff: Designates the roff source file as input which contains the formatted document specifications.
• gropdf: This stage converts the intermediate output into a PDF file, allowing it to be read across various digital platforms and printed without losing format fidelity.
• >: Redirects the output to a specified file destination.
• path/to/output.pdf: This specifies the path and filename for the PDF output file.

Example Output:

A PDF document, output.pdf, that can be opened with any standard PDF reader, ensuring a consistent presentation complete with text, images, and layouts as dictated by the original roff input file.

Conclusion:

The troff command is a versatile tool for document formatting across several platforms, facilitating high-quality outputs in a variety of formats. Whether you’re preparing documents for print, web distribution, or system manuals, troff in combination with groff utilities streamlines the typing and formatting process. By understanding each use case, users can leverage the precise typesetting capabilities of troff to produce professionally presented documentation tailored to specific needs and output formats.