1grog(1) General Commands Manual grog(1)
2
6 grog - “groff guess”—infer the groff command a document requires
7
9 grog [--run] [--ligatures] [groff-option ...] [--] [file ...]
10 grog -h
12 grog --help
13 grog -v
15 grog --version
16
18 grog reads its input and guesses which groff(1) options are needed to
19 render it. If no operands are given, or if file is “-”, grog reads the
20 standard input stream. The corresponding groff command is normally
21 written to the standard output stream. With the option --run, the in‐
22 ferred command is written to the standard error stream and then exe‐
23 cuted.
24
26 -h and --help display a usage message, whereas -v and --version display
27 version information; all exit afterward.
28 --ligatures
30 includes the arguments -P-y -PU in the inferred groff command.
31 These are supported only by the pdf output device.
32 --run writes the inferred command to the standard error stream and
34 then executes it.
35 All other specified short options (that is, arguments beginning with a
37 minus sign “-” followed by a letter) are interpreted as groff options
38 or option clusters with or without an option argument. Such options
39 are included in the constructed groff command line.
40
42 grog reads each file operand, pattern-matching strings that are statis‐
43 tically likely to be characteristic of roff(7) documents. It tries to
44 guess which of the following groff options are required to correctly
45 render the input: -e, -g, -G, -j, -p, -R, -t (preprocessors); and -man,
46 -mdoc, -mdoc-old, -me, -mm, -mom, and -ms (macro packages). The in‐
47 ferred groff command including these options and any file parameters is
48 written to the standard output stream.
49 It is possible to specify arbitrary groff options on the command line.
51 These are included in the inferred command without change. Choices of
52 groff options include -C to enable AT&T troff compatibility mode and -T
53 to select a non-default output device. If the input is not encoded in
54 US-ASCII, ISO 8859-1, or IBM code page 1047, specification of a groff
55 option to run the preconv(1) preprocessor is advised; see the -D, -k,
56 and -K options of groff(1). For UTF-8 input, -k is a good choice.
57 groff may issue diagnostic messages when an inappropriate -m option, or
59 multiple conflicting ones, are specified. Consequently, it is best to
60 specify no -m options to grog unless it cannot correctly infer all of
61 the -m arguments a document requires. A roff document can also be
62 written without recourse to any macro package. In such cases, grog
63 will infer a groff command without an -m option.
64 Limitations
66 grog presumes that the input does not change the escape, control, or
67 no-break control characters. grog does not parse roff input line con‐
68 tinuation or control structures (brace escape sequences and the “if”,
69 “ie”, and “el” requests) nor groff's “while”. Thus the input
70 .if \
71 t .NH 1
72 .if n .SH
73 Introduction
74 will conceal the use of the ms macros NH and SH from grog. Such con‐
75 structions are regarded by grog's implementors as insufficiently common
76 to cause many inference problems. Preprocessors can be even stricter
77 when matching macro calls that bracket the regions of an input file
78 they replace. pic, for example, requires PS, PE, and PF calls to imme‐
79 diately follow the default control character at the beginning of a
80 line.
81 Detection of the -s option (the soelim(1) preprocessor) is tricky; to
83 correctly infer its necessity would require grog to recursively open
84 all files given as arguments to the .so request under the same condi‐
85 tions that soelim itself does so; see its man page. Recall that soelim
86 is necessary only if sourced files need to be preprocessed. Therefore,
87 as a workaround, you may want to run the input through soelim manually,
88 piping it to grog, and compare the output to running grog on the input
89 directly. If the “soelim”ed input causes grog to infer additional pre‐
90 processor options, then -s is likely necessary.
91 $ printf ".TS\nl.\nI'm a table.\n.TE\n" > 3.roff
93 $ printf ".so 3.roff\n" > 2.roff
94 $ printf ".XP\n.so 2.roff\n" > 1.roff
95 $ grog 1.roff
96 groff -ms 1.roff
97 $ soelim 1.roff | grog
98 groff -t -ms -
99 In the foregoing example, we see that this procedure enabled grog to
101 detect tbl(1) macros, so we would add -s as well as the detected -t op‐
102 tion to a revised grog or groff command.
103 $ grog -st 1.roff
105 groff -st -ms 1.roff
106
108 grog exits with error status 1 if a macro package appears to be in use
109 by the input document, but grog was unable to infer which one, or 2 if
110 there were problems handling an option or operand. It otherwise exits
111 with status 0. (If the --run option is specified, groff's exit status
112 is discarded.) Inferring no preprocessors or macro packages is not an
113 error condition; a valid roff document need not use either. Even plain
114 text is valid input, if one is mindful of the syntax of the control and
115 escape characters.
116
118 Running
119 grog /usr/share/doc/groff/meintro.me
120 at the command line results in
121 groff -me /usr/share/doc/groff/meintro.me
122 because grog recognizes that the file meintro.me is written using
123 macros from the me package. The command
124 grog /usr/share/doc/groff/pic.ms
125 outputs
126 groff -e -p -t -ms /usr/share/doc/groff/pic.ms
127 on the other hand. Besides discerning the ms macro package, grog rec‐
128 ognizes that the file pic.ms additionally needs the combination of -t
129 for tbl, -e for eqn, and -p for pic.
130 Consider a file doc/grnexampl.me, which uses the grn preprocessor to
132 include a gremlin(1) picture file in an me document. Let's say we want
133 to suppress color output, produce a DVI file, and get backtraces for
134 any errors that troff encounters. The command
135 grog -bc -Idoc -Tdvi doc/grnexmpl.me
136 is processed by grog into
137 groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me
138 where we can see that grog has inferred the me macro package along with
139 the eqn and grn preprocessors. (The input file is located in /usr/
140 share/doc/groff if you'd like to try this example yourself.)
141
143 grog was originally written in Bourne shell by James Clark. The cur‐
144 rent implementation in Perl was written by Bernd Warken ⟨groff-bernd
145 .warken-72@web.de⟩ and heavily revised by G. Branden Robinson
146 ⟨g.branden.robinson@gmail.com⟩.
147
149 groff(1)
150groff 1.23.0 2 November 2023 grog(1)