preproff is a filter that prepares files of nroff/troff source code for
formatting.  The executable file is in:

	(pathname here)

Run the filter as the first stage in the pipeline that contains tbl, eqn, and
whatever version of troff you are using (in our environment, xroff or a
related program).  This file should provide all the documentation you need to
use it.

Common uses

   You can find exhaustive information on using preproff later in this file.
   The main purpose of preproff is to run off an OSF document that requires
   their special DTE features.  The one feature of general interest, outside
   DTE use, is the -rmboxes option for tables.

   You can perform all the special processing that we normally need to do by
   passing files through preproff with the -standard option.  For instance:

	preproff -st preface.mm > preface.mine
	(further processing of your own on preface.mine)

   If you want finer control -- or just want to know what on earth your doing
   when you invoke preproff -- you will just have to read the rest of this
   file.

   In short, before running off any file of troff/nroff text, pass it through
   preproff with the -xfontfix option.  As a convenience, the program supports
   minimal uniqueness (you can use -xf or even -x instead of the full name
   -xfontfix).

   Another option of preproff might be useful when you have tables and want to
   run the document through nroff.  Some tables contain boxes, which usually
   look bad at the terminal.  You can filter out the tbl commands producing
   boxes through the -rmboxes option:

	preproff -rmb mydoc.1 | tbl | nroff -man | col

   The option removes the words "box", "allbox", and "doublebox" from tbl
   global specifications, and the vertical bars from tbl headers.  (This is
   more than the rmboxes utility offers -- it does not remove vertical
   bars, so tables can come out looking strange.)

   This concludes the quick-and-easy section; the rest is in-depth
   and thorough.


Command line syntax

	As a typical filter program, preproff accepts input from files on the
	command line, from the standard input, or both.  All output goes to
	the standard output.  Thus, the two most common formats are:

	    preproff [ -ARG ] ...     [FILE] ...

	or

	    cat FILE ... | preproff [ -ARG ] ...

	In the first format, arguments and files can be in any order.  An
	initial hyphen marks each argument; other words on the command line
	must be file names.  In the second format, because no file names are
	specified, preproff reads the standard input.

	You can also mix the two formats, if you have an irrepressible urge to
	do so.  preproff recognizes the common UNIX convention in which a
	single hyphen means "take input from the standard input stream here."
	Thus, the following command processes a single stream of troff source
	input, from the three files intro.mm, main.mm, and final.mm in that
	order.

	    cat main.mm | preproff -st intro.mm - final.mm


List of valid arguments

	A lot of different types of filtering are mixed together in this
	utility.  You have to specify at least one argument; otherwise
	preproff passes the input through unchanged.

	The options that the documentation group usually needs can be invoked
	as a group through the -standard option.  However, you can specify
	-standard and then turn off some options by using the -no.  For
	instance, if you want all the standard features except -osf,
	you can enter:

	  preproff -standard -noosf ...

	Here are the arguments in quasi-alphabetical order, with references to
	other sections of this file.


  -d			  (turn off through -nod)
      Process #ifdef lines; an optional following string can be a define.
      Details on this argument can be found in the section
      "Processing #ifdef lines (the -D option)."
      Default, if you specify -standard, is -d.

  -help			  (turn off through -nohelp)
      Print this usage message and then exit.
      Details on this argument can be found by using this argument.
      Default, if you specify -standard, is -nohelp.

  -osf		       (turn off through -osf)
      Change the string "OSF/1" to your own proprietary name.
      Details on this argument can be found in the section
     "Standard processing for OSF-supplied documents."
      Default, if you specify -standard, is -osf.

  -rmpic		  (turn off through -normpic)
      Remove pic (.PS/.PE) figures and insert warnings.
      This just mimics an OSF utility that might be useful for draft copies.
      Default, if you specify -standard, is -normpic.

  -rmboxes		  (turn off through -normboxes)
      Remove "box" and vertical lines from tables.
      Details on this argument can be found in the section "Common uses."
      Default, if you specify -standard, is -normboxes.

  -soelim		  (turn off through -nosoelim)
      Read in files on .so requests, so this program can act on them too.
      Details on this argument can be found in the section
     "Standard processing for OSF-supplied documents."
      Default, if you specify -standard, is -soelim.

  -standard		  (turn off through -nostandard)
      Do all the default processing, plus whatever is specified by other arguments.
      Details on this argument can be found in the section
     "Standard processing for OSF-supplied documents."
      Default is -nostandard.


Short-cuts in specifying arguments

	This program bypasses UNIX conventions as much as possible and provide
	a comfortable set of user options instead.  The conventions described
	here may resemble those of another, much-maligned operating system.

	In each argument, you need to enter just enough initial letters to
	identify it uniquely.  For instance, you can enter -st for
	-standard.

	The purpose of the -no options is described under the section "List of
	valid arguments."

	Uppercase and lowercase letters are interchangeable.  For example,
	-osf is the same as -Osf or -OSF.

	Case is important in -d or -D arguments, though.  These are described
	in the following section.


Processing #ifdef lines (the -D option)

	Unlike the other preproff options, this one preserves the familiar
	syntax of the -D option used in cc and in OSF's rmifdef utility.  You
	can use either -d or -D, but the string that you are defining must be
	in the right case, and must be part of the option (no intervening
	white space).

	Here is a typical use of preproff, defining the strings FOR_REV and
	PIC_OFF.  The -DFOR_REV option means to include sections that begin
	with "#ifdef FOR_REV", and to cut out sections that begin with
	"#ifndef FOR_REV".

	  preproff -DFOR_REV -DPIC_OFF -standard ch1.mm

	If you want #ifdef directives processed with no strings defined, just
	pass -D or -d by itself.

	Some SecureWare documents contain complicated C-like expressions in
	#if statements.  For instance:

	  #if defined(SEC_PRIV) || defined(SEC_MAC)

	While there is no specification of what is valid within this syntax,
	some reasonable processing for such expressions has been incorporated
	into preproff.  The above statement, for instance, is likely to mean
	"Include the following section of text if the user has passed
	-DSEC_PRIV or -DSEC_MAC or both."

	Here are the specifications used by preproff for complex #if
	expressions:

	  The expression can appear in an #if, #ifdef, or #ifndef directive.
	  #if and #ifdef have identical effects, while #ifndef negates
	  (complements) the effect of the expression.  Thus, the following are
	  equivalent:

		#if ! SEC_PRIV
		#ifndef SEC_PRIV

	  Any string or expression can appear within parentheses, which can be
	  nested as much as desired.

	  Any string or parenthesized expression can be preceded by an ! in
	  order to negate (complement) it.  For example, the following
	  expression means, "Include the following section of text if the user
	  has passed neither -DSEC_PRIV nor -DSEC_MAC":

		#if ! ( SEC_PRIV || SEC_MAC )

	  The word "defined" can appear anywhere a string, left parenthesis,
	  or exclamation point is allowed, and is ignored.  This allows
	  constructs like the first example:

		#if defined(SEC_PRIV) || defined(SEC_MAC)

	  Two strings or parenthesized expressions can be separated by one of
	  the following operators:

		& or &&		Logical AND of the expressions

		| or ||		Logical OR of the expressions

		^		Logical XOR (exclusive or) of the expressions

	  An exclamation point is evaluated before one of the above operators.
	  For example, the following expression means, "Include the following
	  section of text if the user has not passed -DSEC_PRIV, but has
	  passed -DSEC_MAC":

		#if ! SEC_PRIV && SEC_MAC

	  But it would be better to write the expression as follows, for the
	  sake of clarity:

		#if ( ! SEC_PRIV ) && SEC_MAC

	  or:

		#if ( ! defined(SEC_PRIV) ) && defined(SEC_MAC)

	  Spaces and tabs are not necessary between tokens, but can be
	  included for ease of reading.  You can put a comment between any
	  tokens or at the end of the line.  The comment uses C syntax.  For
	  example:

		#if ( ! SEC_PRIV /* remove when support added */ ) && SEC_MAC

	Certain other combinations are interpreted without error, but that's
	just to make my parsing easier.  The syntax documented above offers
	more than enough flexibility.


Standard processing for OSF-supplied documents

	The -standard option combines the processing that the doc group needs
	to use in order to produce documentation in our own format:

	  Interpreting OSF-style #ifdef directives (the -D option).

	    This works like OSF's rmifdef utility, but understands constructs
	    within their documentation that it can't handle, and doesn't have
	    its bugs.

	  Changing "OSF/1" to the string used for our proprietary release (the
	  -osf option).

	    When you really want to refer to OSF/1, you have to include some
	    hidden characters, as in the string "OSF\&/1".

	  Reading in files specified by .so requests (the -soelim option).

	    This works like OSF's elimso utility.  This options can be quite
	    useful, because it allows all the other preprocessing to take
	    place on the full troff source, before troff itself is invoked.

	    This option recognizes only .so requests that occur at the
	    beginning of a line.  If you put in something complicated like
	    ".if t .so filename" it will not be discovered and expanded by
	    this option (or by elimso either -- in fact, elimso understands
	    less troff syntax than the -soelim option does).

Source for this program

	The preproff program was developed at Hitachi Computer Products
	(America), Inc., in its Open Systems Division, which is responsible
	for porting and adapting OSF offerings.  Hitachi Computer Products has
	given the program to OSF so it can use and distribute it as part of
	its documentation build tools.  In addition, OSF licensees can adapt
	the program to the needs of their sites.  The program is offered as
	is, with no warranty attached, and so forth and so on.

	You can remove this section from this file before installing it at
	your site.  Most users don't care where something came from, and
	neither should you, except for reporting problems or possible
	improvements.

	Report bugs or suggestions to:

		Hitachi Computer Products, Inc.
		Open Systems Software Development
		Technical Publications Group
		Reservoir Place
		1601 Trapelo Road
		Waltham, Mass.	02154

		e-mail:
		   uunet!hicomb!nancy
                   hicomb!nancy@uunet.uu.net
