Debian Codegraph @

upstream/debian-unstable/man1/grog.1

raw
1 .TH grog 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 grog \- \(lqgroff guess\(rq\(eminfer the
4 .I groff
5 command a document requires
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 1989-2014 Free Software Foundation, Inc.
13 .\" 2021-2023 G. Branden Robinson
14 .\"
15 .\" This file is part of grog, which is part of groff, a free software
16 .\" project. You can redistribute it and/or modify it under the terms
17 .\" of the GNU General Public License version 2 (GPL2) as published by
18 .\" the Free Software Foundation.
19 .\"
20 .\" groff is distributed in the hope that it will be useful, but WITHOUT
21 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
22 .\" or FITNESS FOR A PARTICULAR PURPOSE.
23 .\"
24 .\" The text for GPL2 is available in the internet at
25 .\" <http://www.gnu.org/licenses/gpl2.0.txt>.
26 .
27 .
28 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
29 .do nr *groff_grog_1_man_C \n[.cp]
30 .cp 0
31 .
32 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
33 .nr do-fallback 0
34 .if !\n(.f .nr do-fallback 1 \" mandoc
35 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
36 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
37 .if \n[do-fallback] \{\
38 . de MR
39 . ie \\n(.$=1 \
40 . I \%\\$1
41 . el \
42 . IR \%\\$1 (\\$2)\\$3
43 . .
44 .\}
45 .rr do-fallback
46 .
47 .
48 .\" ====================================================================
49 .SH Synopsis
50 .\" ====================================================================
51 .
52 .SY grog
53 .RI [ groff-option\~ .\|.\|.\&]
54 .RB [ \-\- ]
55 .RI [ file\~ .\|.\|.]
56 .YS
57 .
58 .
59 .P
60 .SY grog
61 .B \-h
62 .YS
63 .
64 .SY grog
65 .B \-\-help
66 .YS
67 .
68 .
69 .P
70 .SY grog
71 .B \-v
72 .YS
73 .
74 .SY grog
75 .B \%\-\-version
76 .YS
77 .
78 .
79 .\" ====================================================================
80 .SH Description
81 .\" ====================================================================
82 .
83 .I grog
84 reads its input
85 and guesses which
86 .MR groff 1
87 options are needed to render it.
88 .
89 If no operands are given,
90 or if
91 .I file
92 is
93 .RB \[lq] \- \[rq],
94 .I grog
95 reads the standard input stream.
96 .
97 The corresponding
98 .I groff
99 command is normally written to the standard output stream.
100 .
101 .
102 .\" ====================================================================
103 .SH Options
104 .\" ====================================================================
105 .
106 .B \-h
107 and
108 .B \-\-help
109 display a usage message,
110 whereas
111 .B \-v
112 and
113 .B \%\-\-version
114 display version information;
115 all exit afterward.
116 .
117 .
118 .P
119 All other specified short options
120 (that is,
121 arguments beginning with a minus sign
122 .RB \[lq] \- \[rq]
123 followed by a letter)
124 are interpreted as
125 .I groff
126 options or option clusters with or without an option argument.
127 .
128 Such options are included in the constructed
129 .I groff
130 command line.
131 .
132 .
133 .\" ====================================================================
134 .SH Details
135 .\" ====================================================================
136 .
137 .I grog
138 reads each
139 .I file
140 operand,
141 pattern-matching strings that are statistically likely to be
142 characteristic of
143 .MR roff 7
144 documents.
145 .
146 It tries to guess which of the following
147 .I groff
148 options are required to correctly render the input:
149 .BR \-e ,
150 .BR \-g ,
151 .BR \-G ,
152 .BR \-j ,
153 .\" gideal is not implemented yet.
154 .\" .BR \-J ,
155 .BR \-p ,
156 .BR \-R ,
157 .\".BR \-s ,
158 .B \-t
159 (preprocessors);
160 and
161 .BR \-man ,
162 .BR \-mdoc ,
163 .BR \-mdoc\-old ,
164 .BR \-me ,
165 .BR \-mm ,
166 .BR \-mom ,
167 and
168 .B \-ms
169 (macro packages).
170 .
171 The inferred
172 .I groff
173 command including these options and any
174 .I file
175 parameters is written to the standard output stream.
176 .
177 .
178 .P
179 It is possible to specify arbitrary
180 .I groff
181 options on the command line.
182 .
183 These are included in the inferred command without change.
184 .
185 Choices of
186 .I groff
187 options include
188 .B \-C
189 to enable AT&T
190 .I troff
191 compatibility mode and
192 .B \-T
193 to select a non-default output device.
194 .
195 If the input is not encoded in
196 ISO\~646:1991\~IRV (US-ASCII)
197 or
198 ISO\~Latin-1 (8859-1),
199 we advise specifying a
200 .I groff
201 option to run
202 .MR preconv 1 ;
203 see the
204 .BR \-D ,
205 .BR \-k ,
206 and
207 .B \-K
208 options of
209 .MR groff 1 .
210 .
211 For UTF-8 input,
212 .B \-k
213 is a good choice.
214 .
215 .
216 .P
217 .I groff
218 may issue diagnostic messages when an inappropriate
219 .B \-m
220 option,
221 or multiple conflicting ones,
222 are specified.
223 .
224 Consequently,
225 it is best to specify no
226 .B \-m
227 options to
228 .I grog
229 unless it cannot correctly infer all of the
230 .B \-m
231 arguments a document requires.
232 .
233 A
234 .I roff
235 document can also be written without recourse to any macro package.
236 .
237 In such cases,
238 .I grog
239 infers a
240 .I groff
241 command without an
242 .B \-m
243 option.
244 .
245 .
246 .\" ====================================================================
247 .SS Limitations
248 .\" ====================================================================
249 .
250 .I grog
251 presumes that the input does not change the escape,
252 control,
253 or no-break control characters.
254 .
255 .I grog
256 does not parse
257 .I roff
258 input line continuation or control structures
259 (brace escape sequences and the
260 .RB \[lq] if \[rq],
261 .RB \[lq] ie \[rq],
262 and
263 .RB \[lq] el \[rq]
264 requests)
265 nor
266 .IR groff 's
267 .RB \[lq] while \[rq].
268 .
269 Thus the input
270 .
271 .RS
272 .EX
273 \&.if \[rs]
274 t .NH 1
275 \&.if n .SH
276 Introduction
277 .EE
278 .RE
279 .
280 conceals the use of the
281 .I ms
282 macros
283 .B NH
284 and
285 .B SH
286 from
287 .IR grog .
288 .
289 Such constructions are regarded by
290 .IR grog 's
291 implementors as insufficiently common to cause many inference problems.
292 .
293 Preprocessors can be even stricter when matching macro calls that
294 bracket the regions of an input file they replace.
295 .
296 .IR pic ,
297 for example,
298 requires
299 .BR PS ,
300 .BR PE ,
301 and
302 .B PF
303 calls to immediately follow the default control character at the
304 beginning of a line.
305 .
306 .
307 .P
308 Detection of the
309 .B \-s
310 option
311 (the
312 .MR \%soelim 1
313 preprocessor)
314 is tricky;
315 to correctly infer its necessity would require
316 .I grog
317 to recursively open all files given as arguments to the
318 .B .so
319 request under the same conditions that
320 .I \%soelim
321 itself does so;
322 see its man page.
323 .
324 Recall that
325 .I \%soelim
326 is necessary only if sourced files need to be preprocessed.
327 .
328 Therefore,
329 as a workaround,
330 you may want to run the input through
331 .I \%soelim
332 manually,
333 piping it to
334 .IR grog ,
335 and compare the output to running
336 .I grog
337 on the input directly.
338 .
339 If the
340 .RI \[lq] \%soelim \[rq]ed
341 input causes
342 .I grog
343 to infer additional preprocessor options,
344 then
345 .B \-s
346 is likely necessary.
347 .
348 .
349 .RS
350 .P
351 .EX
352 $ \c
353 .B printf \[dq].TS\[rs]nl.\[rs]nI\[aq]m a table.\[rs]n.TE\[rs]n\[dq] > \
354 3.roff
355 $ \c
356 .B printf \[dq].so 3.roff\[rs]n\[dq] > 2.roff
357 $ \c
358 .B printf \[dq].XP\[rs]n.so 2.roff\[rs]n\[dq] > 1.roff
359 $ \c
360 .B grog 1.roff
361 groff \-ms 1.roff
362 $ \c
363 .B \%soelim 1.roff | grog
364 groff \-t \-ms \-
365 .EE
366 .RE
367 .
368 .
369 .P
370 In the foregoing example,
371 we see that this procedure enabled
372 .I grog
373 to detect
374 .MR \%tbl 1
375 macros,
376 so we would add
377 .B \-s
378 as well as the detected
379 .B \-t
380 option to a revised
381 .I grog
382 or
383 .I groff
384 command.
385 .
386 .
387 .RS
388 .P
389 .EX
390 $ \c
391 .B grog \-st 1.roff
392 groff \-st \-ms 1.roff
393 .EE
394 .RE
395 .
396 .
397 .\" ====================================================================
398 .SH "Exit status"
399 .\" ====================================================================
400 .
401 .I grog
402 exits with
403 .RB status\~ 1
404 if a macro package appears to be in use by the input document,
405 but
406 .I grog
407 was unable to infer which one,
408 or
409 .B 2
410 if there were problems handling an option or operand.
411 .
412 It otherwise exits with status
413 .BR 0 .
414 .
415 Inferring no preprocessors or macro packages is not an error condition;
416 a valid
417 .I roff
418 document need not use either.
419 .
420 Even plain text is valid input,
421 if one is mindful of the syntax of the control and escape characters.
422 .
423 .
424 .\" ====================================================================
425 .SH Examples
426 .\" ====================================================================
427 .
428 Running
429 .
430 .RS
431 .EX
432 .B grog /usr/\:\%share/\:\%doc/\:\%groff\-base/meintro.me
433 .EE
434 .RE
435 at the command line results in
436 .RS
437 .EX
438 groff \-me /usr/\:\%share/\:\%doc/\:\%groff\-base/meintro.me
439 .EE
440 .RE
441 .
442 because
443 .I grog
444 recognizes that the file
445 .I meintro.me
446 is written using macros from the
447 .I me
448 package.
449 .
450 The command
451 .
452 .RS
453 .EX
454 .B grog /usr/\:\%share/\:\%doc/\:\%groff\-base/pic.ms
455 .EE
456 .RE
457 .
458 outputs
459 .
460 .RS
461 .EX
462 groff \-e \-p \-t \-ms /usr/\:\%share/\:\%doc/\:\%groff\-base/pic.ms
463 .EE
464 .RE
465 .
466 on the other hand.
467 .
468 Besides discerning the
469 .I ms
470 macro package,
471 .I grog
472 recognizes that the file
473 .I pic.ms
474 additionally needs the combination of
475 .B \-t
476 for
477 .IR tbl ,
478 .B \-e
479 for
480 .IR eqn ,
481 and
482 .B \-p
483 for
484 .IR pic .
485 .
486 .
487 .\" XXX: grog no longer (June 2021) attempts to detect this scenario.
488 .\" It's also not a practical one; full-service macro packages don't
489 .\" generally support being "unloaded" for subsequent processing of
490 .\" another document using a different one. We do achieve it, with
491 .\" care, in groff with man(7) and mdoc(7) (see andoc.tmac).
492 .\" .P
493 .\" If both of the former example files are combined in the command
494 .\" .
495 .\" .RS
496 .\" .EX
497 .\" .B grog meintro.me pic.ms
498 .\" .EE
499 .\" .RE
500 .\" .
501 .\" a diagnostic message is sent to the standard error stream because
502 .\" some macro packages cannot be combined.
503 .\" .
504 .\" Nevertheless the corresponding output with the wrong options is
505 .\" written to standard output:
506 .\" .
507 .\" .RS
508 .\" .EX
509 .\" groff \-t \-e \-p \-ms meintro.me pic.ms
510 .\" .EE
511 .\" .RE
512 .\" .
513 .\" and
514 .\" .I grog
515 .\" terminates with an error exit status.
516 .
517 .
518 .P
519 Consider a file
520 .IR \%doc/\:\%grnexampl.me ,
521 which uses the
522 .I \%grn
523 preprocessor to include a
524 .MR gremlin 1
525 picture file in an
526 .I me \" generic
527 document.
528 .
529 Let's say we want to suppress color output,
530 produce a DVI file,
531 and get backtraces for any errors that
532 .I \%troff
533 encounters.
534 .
535 The command
536 .
537 .RS
538 .EX
539 .B grog \-bc \-Idoc \-Tdvi doc/grnexmpl.me
540 .EE
541 .RE
542 .
543 is processed by
544 .I grog
545 into
546 .
547 .RS
548 .EX
549 groff \-bc \-Idoc \-Tdvi \-e \-g \-me doc/grnexmpl.me
550 .EE
551 .RE
552 .
553 where we can see that
554 .I grog
555 has inferred the
556 .I me \" generic
557 macro package along with the
558 .I eqn \" generic
559 and
560 .I grn \" generic
561 preprocessors.
562 .
563 (The input file is located in
564 .I /usr/\:\%share/\:\%doc/\:\%groff\-base
565 if you'd like to try this example yourself.)
566 .
567 .
568 .\" ====================================================================
569 .SH Authors
570 .\" ====================================================================
571 .
572 .I grog
573 was originally written in Bourne shell by James Clark.
574 .
575 The current implementation in Perl was written by
576 .MT groff\-bernd\:.warken\-72@\:web\:.de
577 Bernd Warken
578 .ME
579 and heavily revised by
580 .MT g.branden\:.robinson@\:gmail\:.com
581 G.\& Branden Robinson
582 .ME .
583 .
584 .
585 .\" ====================================================================
586 .SH "See also"
587 .\" ====================================================================
588 .
589 .MR groff 1
590 .
591 .
592 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
593 .cp \n[*groff_grog_1_man_C]
594 .do rr *groff_grog_1_man_C
595 .
596 .
597 .\" Local Variables:
598 .\" fill-column: 72
599 .\" mode: nroff
600 .\" End:
601 .\" vim: set filetype=groff textwidth=72: