gmat</>
<sect1><title>Usage</>
<para>
Usage: <command>gmat</> [switches] filename { [[switches] filename] }
…
</para>
</sect1>
<sect1><title>Description</>
<para>
<command>gmat</> handles the routine processing of text documents into
printed or previewed output. Beginning with one or more input files (in
a formatting language like troff or TeX; or in SGML), <command>gmat</>
performs any necessary preprocessing (e.g. construction of an
<acronym>SGML</acronym> driver file), executes the appropriate
formatter, and previews or prints the resulting output file (generally
PostScript).
</para>
<para>
Most aspects of <command>gmat</> are configurable through command line
switches and/or configuration files. <command>gmat</> reads two
configuration files: the <filename>oratoolsrc</> file and the
<filename>bookfiles</> file.
</para>
<para>
The following command line switches are available:
<variablelist>
<varlistentry><term><option>–d</></term>
<listitem><para>
Enable debugging. If the <option>–d</option> switch is used,
temporary files
created by <command>gmat</> are not deleted when <command>gmat</>
ends.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–f</></term>
<listitem><para>
Keep the output file. If the <option>–f</option> switch is used,
the output file
is not deleted after previewing or printing. Ordinarily,
<command>gmat</> treats the output file as a temporary file.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–F</> <replaceable>file</></term>
<listitem><para>
Specify the name of the output file. The name of the output file
is controlled by the <filename>oratoolsrc</> variable
<literal>PS_BASE</> if the <option>–F</> option is not used.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–k</></term>
<listitem><para>
Keep the formatter input file. The <option>–k</> option is only meaningful
when <acronym>SGML</acronym> files are being processed by
<command>gmat</>. The <acronym>SGML</acronym> file is
automatically translated into a formatter input file; if the <option>–k</>
option isn't used, <command>gmat</> treats the output file as a
temporary file.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–K</> <replaceable>file</></term>
<listitem><para>
Specify the name of the formatter input file. The name of the
formatter input file is controlled by the <filename>oratoolsrc</> variables
<literal>EXT_BASE</> and <literal>EXT3L</> if the <option>–K</> option isn't used.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–o</> <replaceable>pages</></term>
<listitem><para>
Specify a list of pages. Only the pages specified will appear in
the output file. Pages are specified by page number. By default,
all of the pages in the formatter input file will appear in the
output file.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–p</></term>
<listitem><para>
Print the output file. Selection of the output action is
controlled by the <option>–p</> and <option>–v</> options and the <filename>oratoolsrc</>
variable <literal>ACTION</>. If the <option>–p</> option is used, the file will be
printed regardless of the action specified by the <filename>oratoolsrc</>
variable <literal>ACTION</>.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–P</> <replaceable>printer</></term>
<listitem><para>
Select printer. Output will be sent to the printer specified. If
the <option>–P</> option is not used, output will be sent to the printer
specified by the <filename>oratoolsrc</> variable <literal>PRINTER</>. This option has
no meaning if the output file is not printed (e.g. if the
previewer is used instead). Selection of the output action is
controlled by the <option>–p</> and <option>–v</> options and the <filename>oratoolsrc</>
variable <literal>ACTION</>.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–q</></term>
<listitem><para>
Suppress warning messages. The ``verbosity'' of messages is
controlled by the <filename>oratoolsrc</> variables <literal>QUIET</> and <literal>VERBOSE</> and
the <option>–q</> option.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–s</></term>
<listitem><para>
Save the <acronym>SGML</acronym> driver file. If the <option>–s</> option
is not used, <command>gmat</> treats the <acronym>SGML</acronym>
driver file (containing the <!DOCTYPE> declaration and the
locally defined entities) as a temporary file.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–S</></term>
<listitem><para>
Don't merge multiple <acronym>SGML</acronym> files together with
an <acronym>SGML</acronym> driver file. If the <option>–S</> option is
used, <command>gmat</> does not build a driver file. Each
<acronym>SGML</acronym> file must contain it's own <DOCTYPE>
specification. When multiple <acronym>SGML</acronym> files are
given on the command line, <command>gmat</> ordinarily merges them
together in the <acronym>SGML</acronym> driver. If the <option>–S</>
option is specified, each file is processed individually.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–T</> <replaceable>progname</></term>
<listitem><para>
Process the formatter input file with the specified program. This
option is not implemented yet. Ultimately, it will allow
<command>gmat</> to handle arbitrary document formatters instead
of just gtroff.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–v</></term>
<listitem><para>
Preview the output file. Selection of the output action is
controlled by the <option>–p</> and <option>–v</> options and the <filename>oratoolsrc</>
variable <literal>ACTION</>. If the <option>–v</> option is used, the file will be
previewed regardless of the action specified by the <filename>oratoolsrc</>
variable <literal>ACTION</>.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–W</></term>
<listitem><para>
Wait on error. If <command>gmat</> detects a user error (such as
an invalid option) it prints an error message and ends. If the
<option>–W</> option is specified, it also waits for the user to press
Enter. This option is useful if <command>gmat</> is executed by
shell script or batch file and subsequent processing might cause
the error message to scroll off of the screen before it could be
read or even noticed.
</para></listitem>
</varlistentry>
<varlistentry><term><option>–x</></term>
<listitem><para>
Just check for errors. If the <option>–x</> option is specified,
<command>gmat</> does not preview or print the output file.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
The <filename>oratoolsrc</> file provides another way to customize
<command>gmat</>. <command>gmat</> loads each of the following
<filename>oratoolsrc</> files if they exist: the system default file, the user
default file, and the <filename>oratoolsrc</> file in the current directory. If a
variable is set in more than one file, the value in the most recently
loaded file is the value that <command>gmat</> uses.
</para>
<para>
The system default file is <filename>oratoolsrc</>. The location of the system
default file is controlled by the environment variable <systemitem class=environvar>ORALIBDIR</>. If
<systemitem class=environvar>ORALIBDIR</> is not set, the value <filename>/usr/local/prod/lib</> is used. The
user default file is $HOME/.oratoolsrc. The <filename>oratoolsrc</> file in the
current directory is <filename>.oratoolsrc</>.
</para>
<para>
The following variables are recognized by <command>gmat</> in the <literal>GMAT</>
or global sections of the <filename>oratoolsrc</> configuration file.
<variablelist>
<varlistentry><term>action (view, print, check, file)</term>
<listitem><para>
Output file processing. Valid values are view (equivalent to the
<option>–v</> option), print (equivalent to the <option>–p</> option), check
(equivalent to the <option>–x</> option), and file (equivalent to the <option>–f</>
option).
</para></listitem>
</varlistentry>
<varlistentry><term>bindir dir</term>
<listitem><para>
Additional <systemitem class=environvar>PATH</> directory. <command>gmat</> adds the specified
directory to the <systemitem class=environvar>PATH</> environment variable before running
subprocesses. This variable allows the installer to place
<command>gmat</> in a standard place (e.g. <filename>/usr/local/bin</>) but
leave the rest of the executables somewhere else without requiring
that every user update their <systemitem class=environvar>PATH</>.
</para></listitem>
</varlistentry>
<varlistentry><term>bookfiles filename</term>
<listitem><para>
Name of the <filename>bookfiles</> file. The <filename>bookfiles</> file is a
configuration file for a particular book. This variable should be
a simple filename (e.g. <filename>BOOKFILES</>) and not a path name.
</para></listitem>
</varlistentry>
<varlistentry><term>debug boolean</term>
<listitem><para>
Enable debugging? Enabling this variable is equivalent to using
the <option>–d</> option.
</para></listitem>
</varlistentry>
<varlistentry><term>debugdir dir</term>
<listitem><para>
Directory for temporary files. Temporary files are generally
placed in <filename>/tmp</>, but if this variable is set they are stored in
the directory specified. Temporary files are automatically
deleted when <command>gmat</> ends unless debugging is enabled.
</para></listitem>
</varlistentry>
<varlistentry><term>entity_file filename { filename … }</term>
<listitem><para>
Local entities for the <DOCTYPE> declaration. This is used
only if <literal>entities</> is not set in the <filename>BOOKFILES</>
file.
</para></listitem>
</varlistentry>
<varlistentry><term>eqn progname</term>
<listitem><para>
The <command>eqn</> preprocessor to use for gtroff files.
</para></listitem>
</varlistentry>
<varlistentry><term>eqn_opts any</term>
<listitem><para>
Options for <command>eqn</>
</para></listitem>
</varlistentry>
<varlistentry><term>extension_3l ext</term>
<listitem><para>
The default extension for formatter input files.
</para></listitem>
</varlistentry>
<varlistentry><term>ext_base rule</term>
<listitem><para>
The rule for constructing the base filename for the formatter
input file. See below.
</para></listitem>
</varlistentry>
<varlistentry><term>gsoelim progname</term>
<listitem><para>
The <command>gsoelim</> preprocessor to use for gtroff files.
</para></listitem>
</varlistentry>
<varlistentry><term>keep3l boolean</term>
<listitem><para>
Keep the formatter input file?
</para></listitem>
</varlistentry>
<varlistentry><term>macrodir dir</term>
<listitem><para>
Directory where local macro files are kept. This value should be a
path relative to the current directory, for example <filename>./macros</>.
</para></listitem>
</varlistentry>
<varlistentry><term>pic progname</term>
<listitem><para>
The <command>pic</> preprocessor to use for gtroff files.
</para></listitem>
</varlistentry>
<varlistentry><term>pic_opts any</term>
<listitem><para>
Options for <command>pic</>
</para></listitem>
</varlistentry>
<varlistentry><term>printer printer</term>
<listitem><para>
Name of the default printer.
</para></listitem>
</varlistentry>
<varlistentry><term>ps_base rule</term>
<listitem><para>
The rule for constructing the base filename for the output file.
See below.
</para></listitem>
</varlistentry>
<varlistentry><term>quiet</term>
<listitem><para>
Suppress warning messages?
</para></listitem>
</varlistentry>
<varlistentry><term>scriptdir dir</term>
<listitem><para>
Directory where local scripts are kept. This value should be a
path relative to the current directory, for example <filename>./scripts</>.
</para></listitem>
</varlistentry>
<varlistentry><term>seddir dir</term>
<listitem><para>
Directory where <command>sed</> scripts are kept.
</para></listitem>
</varlistentry>
<varlistentry><term>sgmlto3l progname</term>
<listitem><para>
Name of the program that converts an <acronym>SGML</acronym>
document instance into a formatter input file.
</para></listitem>
</varlistentry>
<varlistentry><term>sgml_base rule</term>
<listitem><para>
The rule for constructing the base filename for the
<acronym>SGML</acronym> driver file. See below.
</para></listitem>
</varlistentry>
<varlistentry><term>tbl progname</term>
<listitem><para>
The <command>tbl</> preprocessor to use for gtroff files.
</para></listitem>
</varlistentry>
<varlistentry><term>tbl_opts any</term>
<listitem><para>
Options for <command>tbl</>
</para></listitem>
</varlistentry>
<varlistentry><term>temp_base rule</term>
<listitem><para>
The rule for constructing the base filename for temporary files.
See below.
</para></listitem>
</varlistentry>
<varlistentry><term>verbose boolean</term>
<listitem><para>
Print additional informatory messages?
</para></listitem>
</varlistentry>
<varlistentry><term>wait_on_error boolean</term>
<listitem><para>
Wait on error? Enabling this variable is equivalent to using the
<option>–w</> switch.
</para></listitem>
</varlistentry>
<varlistentry><term>workdir dir</term>
<listitem><para>
Additional <systemitem class=environvar>PATH</> directory. <command>gmat</> adds the specified
directory to the <systemitem class=environvar>PATH</> environment variable before running
subprocesses. Obsolete?
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following variables are recognized by
<command>gmat</> in the <literal>GMAT</> or global sections of the <filename>bookfiles</>
configuration file.
<variablelist>
<varlistentry><term>doctype</term>
<listitem><para>
The <DOCTYPE> definition for the <acronym>SGML</acronym>
driver file. For example, ``book system
“docbook.dtd”''.
</para></listitem>
</varlistentry>
<varlistentry><term>sgmlto3l</term>
<listitem><para>
Name of the program that converts an <acronym>SGML</acronym>
document instance into a formatter input file. If this variable is
specfied in the <filename>bookfiles</> file, it takes precedence over the
value specified in the <filename>oratoolsrc</> file.
</para></listitem>
</varlistentry>
<varlistentry><term>entities filename { filename … }</term>
<listitem><para>
Local entities for the <DOCTYPE> declaration. If this variable
is not set, the value of <literal>entity_file</> from the
<filename>oratoolsrc</> file is used.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<command>gmat</> uses the <filename>bookfiles</> configuration
file to identify options for each file that it processes. Several of
these options only apply to <acronym>SGML</acronym> files and a few only
apply to files processed with the gtroff text formatter.
</para>
<para>
The following variables are recognized by <command>gmat</> in the
section named by the file that is being processed (for example, the
<filename>ch01.sgm</> section when the file <filename>ch01.sgm</> is being processed) or the
global section of the <filename>bookfiles</> configuration file. Options that
apply to the text formatter or text formatter input file (such as
<literal>macros</> and <literal>scripts</>) should only be specified in the global section
of a <filename>bookfiles</> configuration file for <acronym>SGML</acronym> files.
Specifying options for each file does not make sense since they are all
merged into a single driver file.
</para>
<variablelist>
<varlistentry><term>appendix appletter</term>
<listitem><para>
Identifies the file as an appendix and specifies its appendix
letter (i.e. appendix number).
</para></listitem>
</varlistentry>
<varlistentry><term>chapter chapnum</term>
<listitem><para>
Specifies the chapter number of the file.
</para></listitem>
</varlistentry>
<varlistentry><term>not_a_chapter</term>
<listitem><para>
Indicates that the file is not a chapter (or appendix). See
below.
</para></listitem>
</varlistentry>
<varlistentry><term>page number</term>
<listitem><para>
Specifies the starting page number for the file.
</para></listitem>
</varlistentry>
<varlistentry><term>part number</term>
<listitem><para>
Identifies the part of the book that contains the file.
</para></listitem>
</varlistentry>
<varlistentry><term>part<emphasis>n</>_title</term>
<listitem><para>
Specifies the title of the <emphasis>n</>'th part of the book. This
information may be used in page headers or footers, for example.
</para></listitem>
</varlistentry>
<varlistentry><term>pagecount number</term>
<listitem><para>
Identifies how many formatted pages occur in the file. This
information is used by <command>gmat</> to calculate starting page
numbers for files that do not have a <literal>page</> variable. It is
updated automatically each time <command>gmat</> processes the
file.
</para></listitem>
</varlistentry>
<varlistentry><term>macros filenames</term>
<listitem><para>
Identifies the macro packages that should be used when the file is
processed. At present, this option only applies to files
processed with gtroff.
</para></listitem>
</varlistentry>
<varlistentry><term>page number</term>
<listitem><para>
Identifies the starting page of the file.
</para></listitem>
</varlistentry>
<varlistentry><term>scripts prognames</term>
<listitem><para>
A list of scripts that should be used to preprocess the text
formatter input file. Each script must be a filter (accepting
input on <filename>stdin</> and writing output to <filename>stdout</>. The first filter
will recieve the formatter input file as input and the output of
the last filter will become the new formatter input.
</para></listitem>
</varlistentry>
<varlistentry><term>wraptag</term>
<listitem><para>
When <command>gmat</> creates an <acronym>SGML</acronym> driver
file, it inserts the specified tag around the contents of the
files that are processed.
</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1><title>Rules</>
<para>
The values of the <literal>ext_base</>, <literal>sgml_base</>, <literal>ps_base</>, and <literal>temp_base</>
variables are interpreted as filenames with the following extensions. In
order to make it possible for more than one person to work in the same
directory at the same time (or for one person to run several concurrent
<command>gmat</>s), it is neessary to specify that the temporary files
have different names. <command>gmat</> accomplishes this by allowing
you to use the special strings ``$WHOAMI'' and``$PID'' in the value for
each of these variables. In addition, you can use the string
``$BASEFILE'' to refer to the base name of the file that
<command>gmat</> is processing.
</para>
<para>
For example, if ``norm'' processes ``<filename>myfile.tr</>'' with <literal>ps_base</> set
to ``$BASEFILE-$WHOAMI.$PID.ps'' and <command>gmat</> happens to be
process number 3142, the ouput file produced by <command>gmat</> would
be ``<filename>myfile-norm.3142.ps</>''.
</para>
</sect1>
<sect1><title>Chapter and Appendix Numbering</>
<para>
<command>gmat</> assumes that the sections in the <filename>bookfiles</>
configuration file identify the chapters of a book. When files are
listed on the command line, they are reordered into the order that they
appear in the bookfiles file before processing. <command>gmat</>
determines the chapter or appendix number of each chapter and the
starting page number of each chapter by examining the <literal>chapter</>,
<literal>appendix</>, <literal>page</>, and <literal>pagecount</> variables for each file. If a given
file does not have a <literal>chapter</> variable, it is assumed to have a number
one greater than the previous chapter. <command>gmat</> does not
increment the chapter count when it processes a section that has the
<literal>not_a_chapter</> variable set. After the first appendix has been
encountered, <command>gmat</> begins enumerating chapters with letters
rather than numbers.
</para>
</sect1>
<sect1><title>Handling <filename>BOOKFILES</>
The bookfiles file is always read only. You must not
edit the file by hand. Because gmat updates the file each
time it processes a document, any changes that you introduce while
gmat is running will potentially be lost.
Always use the bookfiles program to update the bookfiles
configuration file.
Formating A Document</>
<para>
When formatting a non-SGML document, <command>gmat</> reads the command
line switches and filenames and verifies that they are correct. If all
of the switches are valid, <command>gmat</> checks that each filename
specified exists and that the most recent <acronym>RCS</acronym>
version has been checked out (if applicable).
</para>
<para>
Each filename in turn is passed through the text formatter and the
output file is processed as requested.
</para>
<para>
If switches are used before the first filename, the results of those
switches become the default behavior for the rest of the files specified
on the command line.
</para>
</sect1>
<sect1><title>Formating an SGML Document</>
<para>
Formating and <acronym>SGML</acronym> document is slightly more
complicated than formating a text document. If all of the filenames
listed on the command line end in <filename>.sgm</> or <filename>.sgml</>, <command>gmat</>
assumes that the files are SGML. Unless the <option>–S</> switch is used,
<command>gmat</> will attempt to create a single driver file to process
all of the specified files simultaneously. The general format of the
driver file that <command>gmat</> produces is:
</para>
<screen>
<!DOCTYPE *doctype* [
<!ENTITY file1.sgm SYSTEM "file1.sgm">
<!ENTITY file2.sgm SYSTEM "file2.sgm">
<!ENTITY file3.sgm SYSTEM "file3.sgm">
*local entities*
*wraptag*
<?gmat-file "file1.3l">
<?gmat-part "part title">
<?gmat-chapter-number "1">
<?gmat-page-number "1">
&file1.sgm;
<?gmat-file "file2.3l">
<?gmat-part "part title">
<?gmat-chapter-number "2">
<?gmat-page-number "17">
&file2.sgm;
<?gmat-file "file3.3l">
<?gmat-part "part title">
<?gmat-chapter-number "3">
<?gmat-page-number "23">
&file3.sgm;
*/wraptag*
</screen>
<para>
The files are arranged in the order that they appear in the <filename>bookfiles</>
configuration file regardless of the order specified on the command
line.
</para>
</sect1>
</chapter>
<?troff .BLANK>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-default-dtd-file: "oraprod.ced"
End:
-->