Using the groff command (with examples)
Example 1: Format output for a PostScript printer
groff path/to/input.roff > path/to/output.ps
Motivation: The groff command is used to format and typeset text files, particularly for generating printable documents. By specifying the path to an input file in the roff format, and using the redirection operator > to save the output to a PostScript file, this command allows you to produce a document suitable for printing.
Explanation: In this example, we provide the path to the input file path/to/input.roff. The output of groff will be redirected to the file path/to/output.ps, which will contain the formatted PostScript representation of the input file.
Example Output: The output file path/to/output.ps will be in the PostScript format, ready to be printed or further manipulated using other tools.
Example 2: Render a man page using the ASCII output device, and display it using a pager
groff -man -T ascii path/to/manpage.1 | less --RAW-CONTROL-CHARS
Motivation: Man pages serve as documentation for commands and programs installed on a Unix-like system. By using the groff command, you can render a man page in a human-readable format and view it using a pager, such as less, which allows you to scroll through the content easily.
Explanation: In this example, we specify the -man option to indicate that the input file is a man page. We then use the -T option with the value ascii to specify the ASCII output device. The output of groff is piped to the less command, which is invoked with the --RAW-CONTROL-CHARS option to display the special formatting characters correctly.
Example Output: The man page specified by path/to/manpage.1 will be rendered in ASCII format and displayed in the less pager. You can navigate through the page using standard pager keybindings.
Example 3: Render a man page into an HTML file
groff -man -T html path/to/manpage.1 > path/to/manpage.html
Motivation: HTML is a commonly used format for sharing and displaying formatted documents. By using the groff command with the -T html option, you can generate an HTML version of a man page, which can be viewed in a web browser or shared with others.
Explanation: In this example, the -man option specifies that the input file is a man page. The -T option with the value html tells groff to generate HTML output. The resulting HTML code is then redirected to the file path/to/manpage.html for further use or distribution.
Example Output: The man page specified by path/to/manpage.1 will be converted into an HTML file at path/to/manpage.html. The HTML file can be opened in a web browser, enabling easy navigation and readability.
Example 4: Typeset a roff file containing tables and pictures to PDF
groff -t -p -me -T pdf path/to/input.me > path/to/output.pdf
Motivation: The groff command supports various macros and options, making it suitable for typesetting complex documents with tables and pictures. By combining the -t option for tables, the -p option for pictures, and the -me macro set, you can process a roff file containing such elements and create a formatted PDF output.
Explanation: In this example, the -t option enables table support, while the -p option enables picture support. The -me option specifies the macro set to use, which is a predefined set of macros for formatting documents. Finally, the -T pdf option tells groff to generate PDF output. The resulting PDF is redirected to the file path/to/output.pdf.
Example Output: The roff file specified by path/to/input.me will be typeset, taking into account tables and pictures, using the -me macro set. The resulting PDF will be saved to path/to/output.pdf, ready for viewing or printing.
Example 5: Run a groff command with guessed preprocessor and macro options
eval "$(grog -T utf8 path/to/input.me)"
Motivation: Determining the appropriate preprocessor and macro options for a groff command can be challenging. The grog utility helps simplify this process by analyzing the input file and guessing the correct options. By running grog and passing its output to the eval command, you can automatically execute the groff command with the correct options.
Explanation: In this example, we invoke the grog utility with the -T utf8 option, specifying the desired output encoding. The path to the input file path/to/input.me is provided as an argument. The output of grog is then passed as a command to eval, which executes the groff command with the guessed options.
Example Output: The groff command, with preprocessor and macro options automatically determined by grog, will be executed based on the contents of the file path/to/input.me. The resulting output, encoded as UTF-8, will be displayed in the terminal.
