grog

grog [files...]

-v, --version
    Displays the version information for grog and then exits.
This is a common GNU utility option found in many commands.

files...
    One or more input files to be scanned by grog.
If no files are specified, grog reads from standard input, allowing it to be used in a pipeline.

grog is a utility program integrated within the GNU groff (GNU roff) document formatting system. Its primary purpose is to analyze a given input document and intelligently determine the appropriate groff command-line options and arguments required for its correct processing.
This tool is especially valuable for documents that utilize various groff preprocessors (such as eqn for equations, pic for graphics, tbl for tables, or refer for bibliographies) or specific macro packages (like ms, mm, me, or mandoc).
By outputting the detected options to standard output, grog significantly simplifies the compilation process, helping users automate the groff command line without needing to manually identify all required arguments for complex documents.

grog provides an educated guess; it might not always be perfectly accurate for all groff documents, especially those with highly complex, non-standard, or conditionally compiled structures.
It primarily relies on scanning for specific directive patterns (e.g., lines starting with . or .") and preprocessor calls, which may not cover every possible groff configuration.
Its output is designed to be used with shell command substitution (e.g., groff `grog file`) to automatically pass the detected options to the groff command. grog itself does not execute groff directly after printing its suggestions.

grog is most commonly utilized in shell scripts with command substitution to automatically pass its detected options to the groff command.
For instance, to format a document named my_document.mom that might contain mathematical equations (eqn) and uses the mom macro package, you would typically execute:
groff `grog my_document.mom` > my_document.pdf
In this command, `grog my_document.mom` would output options such as -e -Tps -mom my_document.mom, which are then substituted directly into the groff command line by the shell, simplifying the formatting process.

grog is an integral part of the GNU groff project, which is the GNU implementation of the classic roff and troff text formatting systems.
The original roff (Reversed Off) formatters were developed at Bell Labs in the 1970s, with troff being the typesetting version.
James Clark initiated the GNU groff project in the early 1990s to create a free software replacement for troff.
grog was developed as a complementary utility to simplify the invocation of groff.
It automates the tedious process of identifying necessary preprocessor and macro options for a given document, thereby making the powerful groff system more accessible and user-friendly, especially in automated scripting scenarios.

groff(1), troff(1), eqn(1), pic(1), tbl(1), refer(1), man(1), roff(7)