1GROG(1) General Commands Manual GROG(1)
2
6 grog - guess options for a following groff command
7
9 grog [-C] [-T device] [--run] [--warnings] [--ligatures] [groff-option
10 ...] [--] [filespec ...]
11 grog -h
13 grog --help
14 grog -v
16 grog --version
17
19 grog reads the input (file names or standard input) and guesses which
20 of the groff(1) options are needed to perform the input with the groff
21 program. A suitable device is now always written as -Tdevice including
22 the groff default as -T ps.
23 The corresponding groff command is usually displayed in standard out‐
25 put. With the option --run, the generated line is output into standard
26 error and the generated groff command is run on the standard output.
27 groffer(1) relies on a perfectly running groff(1).
28
30 The option -v or --version prints information on the version number.
31 Also -h or --help prints usage information. Both of these options au‐
32 tomatically end the grog program. Other options are thenignored, and
33 no groff command line is generated. The following 3 options are the
34 only grog options,
35 -C this option means enabling the groff compatibility mode, which
37 is also transfered to the generated groff command line.
38 --ligatures
40 this option forces to include the arguments -P-y -PU within the
41 generated groff command line.
42 --run with this option, the command line is output at standard error
44 and then run on the computer.
45 --warnings
47 with this option, some more warnings are output to standard er‐
48 ror.
49 All other specified short options (words starting with one minus char‐
51 acter -) are interpreted as groff options or option clusters with or
52 without argument. No space is allowed between options and their argu‐
53 ment. Except from the -marg options, all options will be passed on,
54 i.e. they are included unchanged in the command for the output without
55 effecting the work of grog.
56 A filespec argument can either be the name of an existing file or a
58 single minus - to mean standard input. If no filespec is specified
59 standard input is read automatically.
60
62 grog reads all filespec parameters as a whole. It tries to guess which
63 of the following groff options are required for running the input under
64 groff: -e, -g, -G, -j, -p, -R, -s, -t (preprocessors); and -man, -mdoc,
65 -mdoc-old, -me, -mm, -mom, and -ms (macro packages).
66 The guessed groff command including those options and the found file‐
68 spec parameters is put on the standard output.
69 It is possible to specify arbitrary groff options on the command line.
71 These are passed on the output without change, except for the -marg op‐
72 tions.
73 The groff program has trouble when the wrong -marg option or several of
75 these options are specified. In these cases, grog will print an error
76 message and exit with an error code. It is better to specify no -marg
77 option. Because such an option is only accepted and passed when grog
78 does not find any of these options or the same option is found.
79 If several different -marg options are found by grog an error message
81 is produced and the program is terminated with an error code. But the
82 output is written with the wrong options nevertheless.
83 Remember that it is not necessary to determine a macro package. A roff
85 file can also be written in the groff language without any macro pack‐
86 age. grog will produce an output without an -marg option.
87 As groff also works with pure text files without any roff requests,
89 grog cannot be used to identify a file to be a roff file.
90 The groffer(1) program heavily depends on a working grog.
92
94 Calling
95 grog meintro.me
96 results in
97 groff -me meintro.me
98 So grog recognized that the file meintro.me is written with the -me
99 macro package.
100 On the other hand,
101 grog pic.ms
102 outputs
103 groff -p -t -e -ms pic.ms
104 Besides determining the macro package -ms, grog recognized that the
105 file pic.ms additionally needs -pte, the combination of -p for pic, -t
106 for tbl, and -e for eqn.
107 If both of the former example files are combined by the command
108 grog meintro.me pic.ms
109 an error message is sent to standard error because groff cannot work
110 with two different macro packages:
111 grog: error: there are several macro packages: -me -ms
112 Additionally the corresponding output with the wrong options is printed
113 to standard output:
114 groff -pte -me -ms meintro.me pic.ms
115 But the program is terminated with an error code. The call of
116 grog -ksS -Tdvi grnexmpl.g
117 contains several groff options that are just passed on the output with‐
118 out any interface to grog. These are the option cluster -ksS consist‐
119 ing of -k, -s, and -S; and the option -T with argument dvi. The output
120 is
121 groff -k -s -S -Tdvi grnexmpl.g
122 so no additional option was added by grog. As no option -marg was
123 found by grog this file does not use a macro package.
124
126 grog was originally written by James Clark. The current Perl implemen‐
127 tation was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩ with
128 contributions from Ralph Corderoy, and is maintained by Werner Lemberg
129 ⟨wl@gnu.org⟩.
130
132 groff(1), groffer(1)
133groff 1.22.4 19 January 2023 GROG(1)