--- gmat.sgm.orig Thu Jan 1 09:30:00 1970 +++ gmat.sgm Sun Jan 7 12:44:25 2001 @@ -0,0 +1,614 @@ + + +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: +-->