.TH GROG 1 "07 February 2013" "Groff Version 1.22.2"
.
.\" --------------------------------------------------------------------
.\" Legalese
.\" --------------------------------------------------------------------
.
.ig
grog.1 - man page for grog (section 1)

Source file position:  <groff_source_top>/src/roff/grog/grog.man
Installed position:    $prefix/share/man/man1/grog.1

Last Update: 22 Jan 2011
..
.de co
Copyright (C) 1989-2003, 2006, 2007, 2009-2012
Free Software Foundation, Inc.
.
Written by James Clark.
Maintained by
.MT wl@gnu.org 
Werner Lemberg
.ME .
Rewritten and put under GPL by Bernd Warken <groff-bernd.warken-72@web.de>.
.
.P
This file is part of
.IR grog ,
which is part of
.IR groff ,
a free software project.
.
You can redistribute it and/or modify it under the terms of the
.nh
.B "GNU General Public License"
.hy
(\f[CR]GPL\f[]) as published by the
.nh
.BR "Free Software Foundation" ,
.hy
either version\~2, or (at your option) any later version.
.
.P
You should have received a copy of the \f[CR]GNU General Public
License\f[] along with
.IR groff ,
see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
directory of the
.I groff
source package.
.
Or read the
.I man\~page
.BR gpl (1).
You can also write to the
.nh
.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
.BR "MA 02110-1301, USA" .
.hy
..
.
.
.\" --------------------------------------------------------------------
.\" Local macros
.de FN
.I \\$1
..
.
.
.\" --------------------------------------------------------------------
.SH NAME
.
grog \- guess options for groff command
.
.
.\" --------------------------------------------------------------------
.SH SYNOPSIS
.
.SY grog
.OP \-C
.RI [ \%groff\-option\~ .\|.\|.\&]
.OP \-\-
.RI [ \%filespec\~ .\|.\|.]
.
.SY grog
.B \-h
|
.B \-\-help
.
.SY grog
.B \-v
|
.B \-\-version
.YS
.
.
.\" --------------------------------------------------------------------
.SH DESCRIPTION
.
.B grog
reads the input (file names or standard input) and guesses which of
the
.BR groff  (1)
options are needed to perform the input with the
.B groff
program.
.
The corresponding
.B groff
command is output.
.
.
.\" --------------------------------------------------------------------
.SH OPTIONS
.
The only
.B grog
options recognized are
.B \-C
(which is also passed on) to enable compatibility mode;
.B \-v
and
.B \-\-version
print information on the version number; and
.B \-h
and
.B \-\-help
print usage information.
.
.BR \-v ,
.BR \-\-version ,
.BR \-h ,
and
.B \-\-help
stop the program directly without printing a
.B groff
command to standard output.
.
.
.P
All other specified short options (words starting with one minus
character
.BR \- )
are interpreted as
.B groff
options or option clusters with or without argument.
.
No space is allowed between options and their argument.
.
Except from the
.BI \-m arg
options, all options will be passed on, i.e. they are included
unchanged in the command for the output without effecting the work of
.BR grog .
.
.
.P
A
.I filespec
argument can either be the name of an existing file or a single minus
.B \-
to mean standard input.
.
If no
.I filespec
is specified standard input is read automatically.
.
.
.\" --------------------------------------------------------------------
.SH DETAILS
.
.B grog
reads all
.I filespec
parameters as a whole.
.
It tries to guess which of the following
.B groff
options are required for running the input under
.BR groff :
.BR \-e ,
.BR \-man ,
.BR \-me ,
.BR \-mm ,
.BR \-mom ,
.BR \-ms ,
.BR \-mdoc,
.BR \-mdoc-old,
.BR \-p ,
.BR \-R ,
.BR \-g ,
.BR \-G ,
.BR \-s ,
and
.BR \-t .
The guessed
.B groff
command including those options and the found
.I filespec
parameters is put on the standard output.
.
.
.P
It is possible to specify arbitrary
.B groff
options on the command line.
.
These are passed on the output without change, except for the
.BI \-m arg
options.
.
.
.P
The
.B groff
program has trouble when the wrong
.BI \-m arg
option or several of these options are specified.
.
In these cases,
.B grog
will print an error message and exit with an error code.
.
It is better to specify no
.BI \-m arg
option.
.
Because such an option is only accepted and passed when
.B grog
does not find any of these options or the same option is found.
.
.
.P
If several different
.BI \-m arg
options are found by
.B grog
an error message is produced and the program is terminated with an
error code.
.
But the output is written with the wrong options nevertheless.
.
.
.P
Remember that it is not necessary to determine a macro package.
.
A
.I roff
file can also be written in the
.I groff
language without any macro package.
.
.B grog
will produce an output without an
.BI \-m arg
option.
.
.
.P
As
.B groff
also works with pure text files without any
.I roff
requests,
.B grog
cannot be used to identify a file to be a
.I roff
file.
.
.
.P
The
.BR groffer  (1)
program heavily depends on a working
.BR grog .
.
.
.P
The
.B grog
source contains two files written in different programming languages:
.
.ft CB
grog.pl
.ft R
is the
.I Perl
version, while
.ft CB
grog.sh
.ft R
is a shell script using
.BR awk (1).
During the run of
.BR make (1),
it is determined whether the system contains a suitable version of
.BR perl (1).
If so,
.ft CB
grog.pl
.ft R
is transformed into
.BR grog ;
otherwise
.ft CB
grog.sh
.ft R
is used instead.
.
.
.\" --------------------------------------------------------------------
.SH EXAMPLES
.
.IP \(bu
Calling
.
.RS
.IP
.EX
grog meintro.me
.EE
.RE
.
.IP
results in
.
.RS
.IP
.EX
groff \-me meintro.me
.EE
.RE
.
.IP
So
.B grog
recognized that the file
.FN meintro.me
is written with the
.B \-me
macro package.
.RE
.
.
.IP \(bu
On the other hand,
.
.RS
.IP
.EX
grog pic.ms
.EE
.RE
.
.IP
outputs
.
.RS
.IP
.EX
groff \-pte \-ms pic.ms
.EE
.RE
.
.IP
Besides determining the macro package
.BR \-ms ,
.B grog
recognized that the file
.FN pic.ms
additionally needs
.BR \-pte ,
the combination of
.B \-p
for
.IR pic ,
.B \-t
for
.IR tbl ,
and
.B \-e
for
.IR eqn .
.RE
.
.
.IP \(bu
If both files are combined by the command
.
.RS
.IP
.EX
grog meintro.me pic.ms
.EE
.RE
.
.IP
an error message is sent to standard error because
.B groff
cannot work with two different macro packages:
.
.RS
.IP
.ft CR
grog: error: there are several macro packages: -me -ms
.ft
.RE
.
.IP
Additionally the corresponding output with the wrong options is printed
to standard output:
.
.RS
.IP
.EX
groff -pte -me -ms meintro.me pic.ms
.EE
.RE
.
.IP
But the program is terminated with an error code.
.
.
.IP \(bu
The call of
.
.RS
.IP
.EX
grog \-ksS \-Tdvi grnexmpl.g
.EE
.RE
.
.IP
contains several
.B groff
options that are just passed on the output without any interface to
.BR grog .
These are the option cluster
.B \-ksS
consisting of
.BR \-k ,
.BR \-s ,
and
.BR \-S ;
and the option
.B \-T
with argument
.BR dvi .
The output is
.
.RS
.IP
.EX
groff \-ksS \-Tdvi grnexmpl.g
.EE
.RE
.
.IP
so no additional option was added by
.BR grog .
As no option
.BI \-m arg
was found by
.B grog
this file does not use a macro package.
.
.
.\" --------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR groff (1),
.BR troff (1),
.BR tbl (1),
.BR pic (1),
.BR chem (1),
.BR eqn (1),
.BR refer (1),
.BR grn (1),
.BR grap (1),
.BR soelim (1),
.BR groff_me (7),
.BR groff_ms (7),
.BR groff_mm (7),
.BR groff_mom (7),
.BR groff_man (7),
.BR groffer (1)
.
.
.\" --------------------------------------------------------------------
.SH "COPYING"
.
.co
.
.
.\" --------------------------------------------------------------------
.\" Emacs settings
.\" --------------------------------------------------------------------
.
.\" Local Variables:
.\" mode: nroff
.\" End: