# grog - groff guess-infer the groff command a document r... - man(1) - [phpMan] [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) General Commands Manual [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) ## Name grog - “groff guess”—infer the _groff_ command a document requires ## Synopsis **grog **[**--run**] [**--ligatures**] [_groff-option_ ...] [**--**] [_file_ ...] ### grog -h ### grog --help ### grog -v ### grog --version ## Description _grog_ reads its input and guesses which [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) options are needed to render it. If no operands are given, or if _file_ is “**-**”, _grog_ reads the standard input stream. The correspond‐ ing _groff_ command is normally written to the standard output stream. With the option **--run**, the inferred command is written to the standard error stream and then executed. ## Options ### -h --help -v --version all exit afterward. ### --ligatures includes the arguments **-P-y -PU **in the inferred _groff_ command. These are supported only by the **pdf **output device. **--run **writes the inferred command to the standard error stream and then executes it. All other specified short options (that is, arguments beginning with a minus sign “**-**” fol‐ lowed by a letter) are interpreted as _groff_ options or option clusters with or without an op‐ tion argument. Such options are included in the constructed _groff_ command line. ## Details _grog_ reads each _file_ operand, pattern-matching strings that are statistically likely to be characteristic of [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) documents. It tries to guess which of the following _groff_ options are required to correctly render the input: **-e**, **-g**, **-G**, **-j**, **-p**, **-R**, **-t **(preprocessors); and ### -man -mdoc -mdoc-old -me -mm -mom -ms including these options and any _file_ parameters is written to the standard output stream. It is possible to specify arbitrary _groff_ options on the command line. These are included in the inferred command without change. Choices of _groff_ options include **-C **to enable AT&T _troff_ compatibility mode and **-T **to select a non-default output device. If the input is not encoded in US-ASCII, ISO 8859-1, or IBM code page 1047, specification of a _groff_ option to run the [_preconv_(1)](https://www.chedong.com/phpMan.php/man/preconv/1/markdown) preprocessor is advised; see the **-D**, **-k**, and **-K **options of [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). For UTF-8 input, **-k **is a good choice. _groff_ may issue diagnostic messages when an inappropriate **-m **option, or multiple conflicting ones, are specified. Consequently, it is best to specify no **-m **options to _grog_ unless it cannot correctly infer all of the **-m **arguments a document requires. A _roff_ document can also be written without recourse to any macro package. In such cases, _grog_ will infer a _groff_ command without an **-m **option. ### Limitations _grog_ presumes that the input does not change the escape, control, or no-break control charac‐ ters. _grog_ does not parse _roff_ input line continuation or control structures (brace escape sequences and the “**if**”, “**ie**”, and “**el**” requests) nor _groff_'s “**while**”. Thus the input .if \ t .NH 1 .if n .SH Introduction will conceal the use of the _ms_ macros **NH **and **SH **from _grog_. Such constructions are regarded by _grog_'s implementors as insufficiently common to cause many inference problems. Preproces‐ sors can be even stricter when matching macro calls that bracket the regions of an input file they replace. _pic_, for example, requires **PS**, **PE**, and **PF **calls to immediately follow the de‐ fault control character at the beginning of a line. Detection of the **-s **option (the [_soelim_(1)](https://www.chedong.com/phpMan.php/man/soelim/1/markdown) preprocessor) is tricky; to correctly infer its ne‐ cessity would require _grog_ to recursively open all files given as arguments to the **.so **re‐ quest under the same conditions that _soelim_ itself does so; see its man page. Recall that _soelim_ is necessary only if sourced files need to be preprocessed. Therefore, as a workaround, you may want to run the input through _soelim_ manually, piping it to _grog_, and compare the output to running _grog_ on the input directly. If the “_soelim_”ed input causes _grog_ to infer additional preprocessor options, then **-s **is likely necessary. $ **printf ".TS\nl.\nI'm a table.\n.TE\n" > 3.roff** $ **printf ".so 3.roff\n" > 2.roff** $ **printf ".XP\n.so 2.roff\n" > 1.roff** $ **grog 1.roff** groff -ms 1.roff $ **soelim 1.roff | grog** groff -t -ms - In the foregoing example, we see that this procedure enabled _grog_ to detect [_tbl_(1)](https://www.chedong.com/phpMan.php/man/tbl/1/markdown) macros, so we would add **-s **as well as the detected **-t **option to a revised _grog_ or _groff_ command. $ **grog -st 1.roff** groff -st -ms 1.roff ## Exit status _grog_ exits with error status **1 **if a macro package appears to be in use by the input document, but _grog_ was unable to infer which one, or **2 **if there were problems handling an option or operand. It otherwise exits with status **0**. (If the **--run **option is specified, _groff_'s exit status is discarded.) Inferring no preprocessors or macro packages is not an error condi‐ tion; a valid _roff_ document need not use either. Even plain text is valid input, if one is mindful of the syntax of the control and escape characters. ## Examples Running **grog /usr/share/doc/groff-base/meintro.me** at the command line results in groff -me /usr/share/doc/groff-base/meintro.me because _grog_ recognizes that the file _meintro.me_ is written using macros from the _me_ package. The command **grog /usr/share/doc/groff-base/pic.ms** outputs groff -e -p -t -ms /usr/share/doc/groff-base/pic.ms on the other hand. Besides discerning the _ms_ macro package, _grog_ recognizes that the file _pic.ms_ additionally needs the combination of **-t **for _tbl_, **-e **for _eqn_, and **-p **for _pic_. Consider a file _doc/grnexampl.me_, which uses the _grn_ preprocessor to include a [_gremlin_(1)](https://www.chedong.com/phpMan.php/man/gremlin/1/markdown) picture file in an _me_ document. Let's say we want to suppress color output, produce a DVI file, and get backtraces for any errors that _troff_ encounters. The command **grog -bc -Idoc -Tdvi doc/grnexmpl.me** is processed by _grog_ into groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me where we can see that _grog_ has inferred the _me_ macro package along with the _eqn_ and _grn_ pre‐ processors. (The input file is located in _/usr/share/doc/groff-base_ if you'd like to try this example yourself.) ## Authors _grog_ was originally written in Bourne shell by James Clark. The current implementation in Perl was written by [Bernd Warken](mailto:) and heavily revised by [G. Branden Robinson](mailto:). **See also** [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) groff 1.23.0 31 March 2024 [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown)