Name¶

grog - “groff guess”—infer thegroffcommand a document requires

Synopsis¶

Description¶

grogreads its inputand guesses whichgroff(1)options are needed to render it.If no operands are given,or iffileis“-”,grogreads the standard input stream.The correspondinggroffcommand is normally written to the standard output stream.With the option--run,the inferred command is written to the standard error stream and thenexecuted.

Options¶

-hand--helpdisplay a usage message,whereas-vand--versiondisplay version information;all exit afterward.

--ligatures

includes the arguments-P-y -PUin the inferredgroffcommand.These are supported only by thepdfoutput device.

--run

writes the inferred command to the standard error stream and thenexecutes it.

All other specified short options(that is,arguments beginning with a minus sign“-”followed by a letter)are interpreted asgroffoptions or option clusters with or without an option argument.Such options are included in the constructedgroffcommand line.

Details¶

grogreads eachfileoperand,pattern-matching strings that are statistically likely to becharacteristic ofroff(7)documents.It tries to guess which of the followinggroffoptions 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 inferredgroffcommand including these options and anyfileparameters is written to the standard output stream.

It is possible to specify arbitrarygroffoptions on the command line.These are included in the inferred command without change.Choices ofgroffoptions include-Cto enable AT&Ttroffcompatibility mode and-Tto select a non-default output device.If the input is not encoded in US-ASCII,ISO 8859-1,or IBM code page 1047,specification of agroffoption to run thepreconv(1)preprocessor is advised;see the-D,-k,and-Koptions ofgroff(1).For UTF-8 input,-kis a good choice.

groffmay issue diagnostic messages when an inappropriate-moption,or multiple conflicting ones,are specified.Consequently,it is best to specify no-moptions togrogunless it cannot correctly infer all of the-marguments a document requires.Aroffdocument can also be written without recourse to any macro package.In such cases,grogwill infer agroffcommand without an-moption.

.if \
t .NH 1
.if n .SH
Introduction

$ 
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 -

$ 
grog -st 1.roff
groff -st -ms 1.roff

Exit status¶

grogexits with error status1if a macro package appears to be in use by the input document,butgrogwas unable to infer which one,or2if there were problems handling an option or operand.It otherwise exits with status0.(If the--runoption is specified,groff'sexit status is discarded.)Inferring no preprocessors or macro packages is not an error condition;a validroffdocument 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/share/doc/groff-base/meintro.me

groff -me /usr/share/doc/groff-base/meintro.me

grog /usr/share/doc/groff-base/pic.ms

groff -e -p -t -ms /usr/share/doc/groff-base/pic.ms

Consider a filedoc/grnexampl.me,which uses thegrnpreprocessor to include agremlin(1)picture file in anmedocument.Let's say we want to suppress color output,produce a DVI file,and get backtraces for any errors thattroffencounters.The command

grog -bc -Idoc -Tdvi doc/grnexmpl.me

groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me

Authors¶

grogwas originally written in Bourne shell by James Clark.The current implementation in Perl was written byBernd Warkenand heavily revised byG. Branden Robinson.

See also¶

groff(1)