1 BOXES
!
Utility to allow documents produced on VAX/VMS systems to easily use the
line-drawing character set present on most terminals and many printers.

Format:  	$  BOXES  input_file  [qualifiers]

BOXES converts all tabs to blanks using the standard 8-column settings.
!
2 Description
!
The BOXES command converts 'boxes' in the input document which look like:
)0
            +-----+                                 lqqqqqk
            | BOX |   into boxes which look like:   x BOX x.
            +-----+                                 mqqqqqj

The BOXES command only does this within regions in the input document which
are surrounded by lines containing the character string '[][]'.  In this
HELP text this is referred to as regions where "box building is enabled"

The boxes in the input document must be built using plus signs, minus signs,
and vertical bars.  Plus signs must be used at every corner or intersection.
!
3 Example
!
  Input    Output
 +--+--+   +--+--+    This box does not appear between lines containing 
 |  |  |   |  |  |    '[][]' so it does not get converted to solid lines.
 +--+--+   +--+--+
 |  |  |   |  |  |
 +--+--+   +--+--+
 [][]      )0
 +--+--+   lqqwqqk    This box DOES appear within the '[][]' delimiters,
 |  |  |   x  x  x    so it is converted.  Note that BOXES removes the
 +--+--+   tqqnqqu    delimiters, and is clever enough to tell which
 |  |  |   x  x  x    line-drawing character to use at each corner and
 +--+--+   mqqvqqj    intersection.
 [][]
!
3 Delimiter
!
The BOXES utility only operates on certain sections of the input document.
Placing the sequence of characters  [][]  anywhere on a line alternately
enables and disables box construction.  The sequence itself won't appear
in the output document (but if it is on a line by itself, a blank line
will appear).  Examples:
 
 A.  [][]           (enable box building, blank line output)
     +-----+
     |     |
     +-----+
     [][]           (disable box building, blank line output)
 
 
 B.  [][]+-----+    (enable box building, top line of box output)
     |     |
     [][]+-----+    (disable box building, bottom line of box output)
 
 
 C.  +-----+ [][]   (same as example B above)
     |     |
     +-----+ [][]

Note that the enabling and/or disabling sequences can appear on a line
with box data; all lines containing sequences are defined to be WITHIN
enabled areas.  In example B above, the box will be constructed properly
when the sequences are removed by BOXES.  Normally, the sequences are
placed on separate lines, since it is usually desired to have some blank
space around boxes.  Box building should be kept disabled unless actually
needed, because it causes lots of extra computation to be performed.

As example B shows, BOXES normally removes the sequences, but sometimes
you may rather have BOXES convert the sequences to blanks.  You can do
this by using the /NOREMOVE qualifier.
 
If the sequence  [][]  is inconvenient to use,  you may choose any string
in its place.  You use the /DELIMITER qualifier to tell BOXES what your
sequence is.  For example, to use  \\\  as the sequence, execute BOXES as:
 
             $  BOXES  /DELIMITER="\\\"  input_file  [qualifiers]
!
3 Rules
!
If the box characters  + , - , |  are used when box building is disabled,
then they are treated as normal text.  The following rules apply when box
building is enabled:
 
* If a box character appears in a position  where it cannot be connected
  to another box character, then it is treated as normal text.   For ex-
  ample, the characters in the center of the three boxes below cannot be
  connected to the boxes,  even though they are surrounded  on all sides
  by box characters,  because there are no intersections  ('+'s)  in the
  necessary positions:
                       +-+             +-+             +-+
                       |+|             |-|             |||
                       +-+             +-+             +-+
 
* There may  be situations where you need to print  a real plus or minus
  sign in or near  a box.   This will  usually work correctly,  since it
  will probably not be in a position to mistakenly become part of a box.
  You can also define an  Accept Flag,  which can be placed  immediately
  preceeding any character  to prevent BOXES from treating the character
  specially.  You use the /ACCEPT qualifier to define an Accept flag, as
  in the examples:
 
                         $ BOXES /ACCEPT="%" . . .
 
                         $ BOXES /ACCEPT . . .
 
  The first example defines the percent sign as the Accept Flag, and the
  second example defines the default Accept Flag, which is the cent sign
  (¢, enter on terminal by typing  COMPOSE C /  ).

--------------------------------------------------------------------------

When a  +  is used in box construction, and it does not appear at a corner
or an intersection of two lines (i.e. it appears at the end of, or in the
middle of, a simple straight line), it causes a "tic mark" to be drawn.
If the line is horizontal, the tic mark will point upwards; if the line is
vertical, it will point to the left.
 
There may be times when you need tic marks drawn in other directions; this
can be done by defining and using a Force Flag.  You use the /FORCE qual-
ifier to define an Force flag, as in the examples:
 
                 $ BOXES /FORCE="%" . . .
 
                 $ BOXES /FORCE . . .
 
The first example defines the percent sign as the Force Flag, and the sec-
ond example defines the default Force Flag,  which is the copyright sign
(©, enter on terminal by typing  COMPOSE C O  ).
 
When a Force Flag is placed adjacent to a '+', it will print as a blank,
but will act as a box-building character.  This can best be described by
example:  the three samples below will create horizontal lines with tic
marks.  The left one will have tic marks going up, the others going down;
the middle one will have long tic marks, the others short ones.
 
Input:       +-+-+-+-+       +-+-+-+-+       +-+-+-+-+
                             | | | | |       © © © © ©
)0
Output:      mqvqvqvqj       lqwqwqwqk       lqwqwqwqk
                             x x x x x

--------------------------------------------------------------------------

The BOXES utility checks for escape sequences, and assumes all are non-
printing (i.e. take up 0 columns on the output device).  The following
example input will print as a box with BOLDed contents; assume * is the
ESCAPE character:
			+----------------+         [][]
			| *[1mThis is bolded*[m |
			+----------------+
!
2 Parameter
!
  input_file

    The name of the input file to BOXES is a required parameter.  If no
    file type is supplied, the file type is assumed to be '.DOC'.
!
2 Qualifiers
!
/OUTPUT
!
  /OUTPUT=output_file

    Specifies the name of the output file for BOXES.  If no file type is
    given, '.BOX' is used.

    If the /OUTPUT qualifier is not used, the output from BOXES goes to a
    file with the same name as the input file, but with a file type of
    '.BOX'.
!
/DELIMITER
!
    /DELIMITER="string"

    Allows use of a different sequence other than the default "[][]" to
    delimit regions of box building.

    The delimiter may appear on a line by itself, or with preceding or
    following text.  By default, the BOXES utility removes the delimiter
    from the line, as in:

		Before:  some [][] text
		After:   some  text

    If desired, you can use the /NOREMOVE qualifier to have the BOXES
    replace the delimiter with blanks, as in:

		Before:  some [][] text
		After:   some      text
!
/REMOVE
!
    /REMOVE  (default)
    /NOREMOVE

    Defines how BOXES handles the delimiter string.  The delimiter is
    usually "[][]", but can be changed using the /DELIMITER qualifier.
    By default, BOXES removes the delimiter, as in:

		Before:  some [][] text
		After:   some  text

    If the /NOREMOVE qualifier is present, BOXES replaces the delimiter
    with blanks, as in:

		Before:  some [][] text
		After:   some      text
!
/ACCEPT
!
    /ACCEPT
    /ACCEPT="char"

    Defines an Accept Flag for BOXES, much like the RUNOFF Accept Flag.
    Characters following this character are not specially processed by the
    BOXES utility.  By default, no Accept Flag is defined.  If /ACCEPT is
    specified with no character, then "¢" (Cent Sign) is used as the
    Accept Flag.  The Cent Sign can be entered using the sequence

                                COMPOSE C /
!
/FORCE
!
    /FORCE
    /FORCE="char"

    Defines a Force Flag, as described in HELP BOXES DESCRIPTION RULES.  By
    default, no Force Flag is defined.  If /FORCE is specified with no
    "char", then "©" (Copyright Sign) is used as the Force Flag.  The Copy-
    right Sign can be entered using the sequence

                                COMPOSE C O
!
/VERSION
!
    Causes BOXES to display  on the SYS$OUTPUT file its current version num-
    ber and date, in the format:

        NSWC BOXES Rev n.nnn Created dd-mmm-yyyy hh:mm

    If /VERSION is used,  but no input_file specification is supplied on the
    command line, then it displays the version information and exits without
    processing a document.   If a file specification is supplied, BOXES dis-
    plays the version and processes the document as specified.
!
