Debian Codegraph @

upstream/debian-trixie/man1/grog.1

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