--- gmat.sgm.orig Thu Jan 1 09:30:00 1970
+++ gmat.sgm Sun Jan 7 12:44:25 2001
@@ -0,0 +1,614 @@
+<!-- $Id: gmat.sgm 1.2 1994/08/29 17:53:27 norm Exp $ -->
+
+<chapter id=gmat><title>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</></title>
+
+<para>
+The <filename>bookfiles</> file is <emphasis>always</> read only. You must not
+edit the file by hand. Because <command>gmat</> updates the file each
+time it processes a document, any changes that you introduce while
+<command>gmat</> is running will potentially be lost.
+</para>
+
+<para>
+Always use the <command>bookfiles</> program to update the <filename>bookfiles</>
+configuration file.
+</para>
+
+</sect1>
+<sect1><title>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:
+-->
