nroff Command in Linux
The nroff command in Unix/Linux is used to format and display text files for printing or viewing on a terminal. It's part of the troff suite, which is often used for creating manual pages, reports, and other formatted documents.
- nroff stands for "new roff" and is typically used for formatting text in a simpler manner compared to troff, which offers more advanced typesetting.
- nroff can handle basic formatting such as line breaks, justification, and font styles (bold, italics, etc.). Unlike troff, which is intended for preparing documents for printing on a typesetter, nroff produces output formatted for display on a terminal and uses macros to define how text is formatted.
- The nroff script is essentially an emulation of the original nroff command, leveraging the capabilities of groff. This allows for extensive formatting options for textual documents, particularly for man pages.
The "-T" option specifies the output device. It accepts values like ascii, ascii8, latin1, utf8, nippon, and cp1047. If no valid -T option is provided, nroff defaults to checking the system locale settings (using the locale program or environment variables like LC_ALL, LC_CTYPE, LANG, and LESSCHARSET) to determine the appropriate output device.
The environment variable GROFF_BIN_PATH defines a colon-separated list of directories where the system should search for the groff executable before checking the default system PATH. If GROFF_BIN_PATH is not set, the default directory used for this purpose is /usr/bin. This allows you to customize the search path for groff executables, ensuring that the appropriate version or custom installation is used.
Table of Contents
Here is a comprehensive guide to the options available with the nroff command â
Syntax of nroff Command
The general syntax for the nroff command is as follows:
nroff [options] file
nroff Command Options
The following table provides a detailed description of the different formatting options available for the nroff command:
| Options | Description |
|---|---|
| -h | Use tabs in the output (equivalent to grottyâs -h option). |
| -c | Use the old output scheme instead of SGR escape sequences. |
| -C | Various controls as described in the troff command. |
| -I | Ignore missing output files; continue processing. |
| -n | Specify the starting page number. |
| -m | Specify a macro package to use (e.g., -man for manual pages). |
| -o | Specify pages to be output (e.g., -o3-5 for pages 3 to 5). |
| -p | Preprocess with pic for handling diagrams (passed to groff). |
| -r | Specify register values (e.g., -rS11 sets register S to 11). |
| -S | Enable safer mode, preventing potentially unsafe operations (passed to groff). |
| -t | Preprocess with tbl for handling tables (passed to groff). |
| -T | Specify the output device (e.g., utf8, ascii, latin1, etc.). |
| -U | Enable unsafe mode, allowing potentially unsafe operations (passed to groff). |
| -v | Display the version number of the nroff script. |
| -e | Silently ignored (not implemented in troff). |
| -q | Silently ignored (not implemented in troff). |
| -s | Silently ignored (not implemented in troff). |
| -d ctext | Set a string as a register value. |
| -d string=text | Set a string value for a register. |
| -K fallback-encoding | Specify a fallback encoding. |
| -M macro-directory | Specify the directory for macro packages. |
| -P postprocessor-argument | Pass an argument to the postprocessor. |
| -w warning-category | Specify the warning category to enable. |
| -W warning-category | Specify the warning category to disable. |
Examples of nroff Command in Linux
In this section, weâll explore various practical examples that will help you make the most of the nroff command.
- Formatting a Manual Page for Display
- Formatting for UTF-8 Output
- Using Tabs in the Output
- Specifying the Starting Page Number
- Specifying the Output Device for ASCII
- Processing Diagrams with pic
- Formatting and Specifying the Starting Page Number
- Enabling the Safe Mode
- Handling Tables with tbl
- Displaying the Version Number
Formatting a Manual Page for Display
To format a manual page for display on a terminal screen, you can use the following command:
sudo nroff -man myfile.1
This command processes the myfile.1 file using the man macros and outputs it in a readable format, making it easy to read directly on the terminal.
Formatting for UTF-8 Output
To format a document for UTF-8 output, which is useful for displaying characters from multiple languages, you can simply use the nroff command with the "-T" flag:
sudo nroff -Tutf8 myfile.txt
This command is especially useful if your document contains Unicode characters (e.g., non-Latin scripts like Arabic, Chinese, or emojis), and you want to ensure that the output displays them properly in the terminal or other UTF-8-compatible environments.
Using Tabs in the Output
To utilize tabs in the formatted output, which can be useful for aligning text in columns, simply run:
sudo nroff -h myfile.txt
This command instructs nroff to use tabs instead of spaces for indentation, helping to maintain consistent column alignment in the output.
Specifying the Starting Page Number
To specify the starting page number when formatting a document, you can use the following command:
sudo nroff -n 5 myfile.txt
This command sets the starting page number to 5, which is particularly useful when generating multi-page documents and you need to continue from a specific page number.
Specifying the Output Device for ASCII
To format a document and specify the output device for ASCII characters, you can use the nroff command with the -Tascii option:
sudo nroff -Tascii myfile.txt
This ensures that the output is suitable for ASCII devices, which is especially useful for plain text environments.
Processing Diagrams with pic
To preprocess a document with pic for handling diagrams, you can use the following command:
sudo nroff -p myfile.txt
This command sends the document through pic before formatting, enabling the inclusion of diagrams and other graphical elements in the final output.
Formatting and Specifying the Starting Page Number
To format a document and specify the starting page number, you can use the nroff command with the "-n" flag:
sudo nroff -n 5 myfile.txt
This command sets the starting page number to 5, ensuring that the formatted output begins at page 5. This is useful when you need to merge multiple documents or continue a document from a specific point, maintaining the correct page numbering.
Enabling the Safe Mode
To enable the safe mode, which prevents potentially unsafe operations during formatting, you can use the following command:
sudo nroff -S myfile.txt
This command ensures that any unsafe or potentially harmful operations are disabled, providing an added layer of security when processing documents.
Handling Tables with tbl
To preprocess a document with tbl for handling tables, you can use the following command:
sudo nroff -t myfile.txt
This command sends the document through tbl before formatting, ensuring that any tables included in the file are properly structured and displayed.
Displaying the Version Number
To display the version number of the nroff script, simply run:
sudo nroff -v
This command outputs the current version number of the nroff script, which is useful for verifying the installed version and ensuring compatibility with your documents.
Conclusion
The nroff command is a versatile and robust tool for formatting text documents in Unix/Linux environments. It provides various options for customizing output, including support for macros, page formatting, and different output encodings like UTF-8.
Whether you're creating manual pages, processing diagrams, or handling special characters, nroff offers flexibility and control. By understanding its syntax and available options, you can efficiently format documents for terminal display or printing, ensuring that the output meets your specific needs.