# grog

## Name



           grog - “groff guess”—infer the _groff_ command a document requires
    


## Synopsis



           **grog**[_groff-option_ ...] [**--**] [_file_ ...]
    
           **grog -h**
    
           **grog --help**
    
           **grog -v**
    
           **grog --version**
    


## Description



           _grog_ reads its input and guesses which _groff_(1) options are needed
           to render it.  If no operands are given, or if _file_ is “**-** ”, _grog_
           reads the standard input stream.  The corresponding _groff_ command
           is normally written to the standard output stream.
    


## Options



           **-h** and **--help** display a usage message, whereas **-v** and **--version**
           display version information; all exit afterward.
    
           All other specified short options (that is, arguments beginning
           with a minus sign “**-** ” followed by a letter) are interpreted as
           _groff_ options or option clusters with or without an option
           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) 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** , and
           **-ms**(macro packages).  The inferred _groff_ command 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 ISO 646:1991 IRV (US-ASCII) or
           ISO Latin-1 (8859-1), we advise specifying a _groff_ option to run
           the _preconv_(1;) see the **-D** , **-k** , and **-K** options of _groff_(1).  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 characters.  _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.
           Preprocessors 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
           default control character at the beginning of a line.
    
           Detection of the **-s** option (the _soelim_(1) preprocessor) is tricky;
           to correctly infer its necessity would require _grog_ to recursively
           open all files given as arguments to the **.so** request 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) 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 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**.  Inferring no preprocessors or
           macro packages is not an error condition; 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/local/share/doc/groff-1.23.0/meintro.me**
           at the command line results in
                  groff -me /usr/local/share/doc/groff-1.23.0/meintro.me
           because _grog_ recognizes that the file _meintro.me_ is written using
           macros from the _me_ package.  The command
                  **grog /usr/local/share/doc/groff-1.23.0/pic.ms**
           outputs
                  groff -e -p -t -ms /usr/local/share/doc/groff-1.23.0/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) 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_ preprocessors.  (The input file is located in
           _/usr/local/share/doc/groff-1.23.0_ 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
           ⟨groff-bernd.warken-72@web.de⟩ and heavily revised by G. Branden
           Robinson ⟨g.branden.robinson@gmail.com⟩.
    


## See also



           _groff_(1)
    


* * *