mirror of
https://git.freebsd.org/ports.git
synced 2025-06-17 18:50:33 -04:00
Add a bare-bones document (gmat.sgm) describing how to use gmat. Catch 22: to read this, you need to format it with gmat. To format it with gmat, you need first to read it.
617 lines
25 KiB
Text
617 lines
25 KiB
Text
--- 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:
|
|
+-->
|