PC World 2000 February/PCWorld_2000-02_cd.bin/Software/Servis/FFE/GRAPH.SWG/0035_RIP Scrip.pas/RIPSCRIP.ZIP/RIPSCRIP.DOC

Text File | 1995-10-01 | 170.6 KB | 4,044 lines

                   ------------------------------------------
                    RIPscrip Graphics Protocol Specification

                           "Remote Imaging Protocol"

                   Copyright (c) 1992-1993, TeleGrafix Corporation
                              All Rights Reserved

                                Revision 1.52.00

                                April 20th, 1993
                   ------------------------------------------
                       with editing by Bob Stein, 10/10/92




     =====================================================================
     ==                           INTRODUCTION                          ==
     =====================================================================

     As system operators of many bulletin board systems, we've often
     wished for some form of Graphical User Interface for our boards. Like
     most Sysops, we've come across many solutions.  But they all seemed
     to fall short in one way or another:  inadequate for THIS system,
     incomplete, difficult to implement, too complex, or lacking in
     graphics development tools.  In short, we became frustrated.

     So, we decided to write our own Graphical Script Language.

     RIPscrip stands for "Remote Imaging Protocol Script" language.  This
     graphical language is our answer to the graphics needs of the BBS
     community and has serious tools for implementation and practical use.

     For more information on RIPaint, RIPterm or RIPscrip development
     tools, contact:

          TeleGrafix Corporation
          16458 Bolsa Chica, #15
          Huntington Beach, CA 92649

          VOICE: [phone]
          FAX  : [phone]
          DATA : [phone] (ArenaBBS: The Major BBS...32 lines)



          ResNova Software
          16458 Bolsa Chica, #193
          Huntington Beach, CA 92649

          VOICE: [phone]
          FAX  : [phone]
          DATA : [phone] (Nova Central: Nova Link Pro...4 lines)



          RIP Demo Midwest

          VOICE: [phone]
          DATA : [phone] (RIP Demo Midwest BBS: TBBS...2 lines)
          FAX  : [phone]



     =====================================================================
     ==                            DEFINITION                           ==
     =====================================================================

     RIPscrip is a text based Script language for displaying online
     graphics.  The script language conforms to 7-bit ASCII, avoiding the
     use of Extended ASCII characters.  This allows transmission over X.25
     networks and other carriers that do not support full 8-bit binary
     transfers easily.  RIPscrip allows RIPscrip graphical statements to
     be mixed with printable ASCII text and [de facto standard]
     ANSI/VT-100 directives.  RIPscrip can dynamically determine what is
     graphics and what is text and display them appropriately in separate
     windows (a graphics window and a text window).  And if you must have
     your own proprietary commands, RIPscrip has room for that too.





     =====================================================================
     ==                     HOW DOES RIPscrip WORK?                     ==
     =====================================================================

     RIPscrip uses a flexible, and very efficient script language for its
     graphical statements.  Its efficiency stems from its compactness and
     developmental planning.  It is entirely Object Oriented instead of
     Raster Oriented for efficient transmission of data and powerful
     editing capabilities (using RIPaint for example).  The language is
     open ended enough so that literally trillions of different graphics
     commands can be implemented as needed.  RIPscrip is not a proprietary
     protocol standard and is open to suggestion from the rest of the
     world.

     Earlier Graphical Script Languages (Avatar and Skypix among others),
     utilize special command characters to indicate which graphics command
     is to be executed.  This precludes their use on systems that are
     limited to ASCII printable text.  Traditional script languages use
     English words to accomplish things (eg, "BOX 0,0 100,50").  This kind
     of thing is incredibly bulky, especially when you consider that
     pictures are usually not simple things, but comprised of hundreds or
     thousands of individual graphical operations (eg, line, circles,
     fills, text, etc.).  With this in mind, a human-readable script
     language was completely inappropriate for the relatively limited
     bandwidth of conventional modems.

     So, one of our main strategies for this language was to make it as
     efficient as possible without going completely binary.  This allows
     the immediate installation of the protocol onto any ASCII text-based
     host system -- because the language consists entirely of ASCII
     printable characters.  We justify the unreadability of the language
     by pointing out the limitations of today's modems and phone lines --
     the language must be compact.




     =====================================================================
     ==              RIPscrip PROTOCOL - GENERAL STRUCTURE              ==
     =====================================================================

     This document describes RIPscrip commands and functions supported
     with RIPterm v1.02.

     RIPscrip is organized into 10 levels of graphical commands (low
     Level-0 to high Level-9).  Level-0 commands are the building blocks
     of RIPscrip.  The basic graphics primitives of the system are all
     Level-0, including the commands LINE, RECTANGLE, CIRCLE, COLOR, FONT,
     etc.  Each level of RIPscrip gets progressively higher-level in
     concept.  For example, Level-1 commands use Mouse Regions, Icons, and
     Formatted Text Regions.

     The basic Syntax Rules are as follows:

          1.  A RIPscrip command line starts at the beginning of a
              line of text.  A RIPscrip command line moved to the
              middle of a line of text is treated as literal text.
              This prevents people inserting mischievous things in
              teleconference messages, or similar pranks.  The only
              exception to this rule is stated below under item 6,
              "continuation of long lines".

          2.  A RIPscrip command line begins with an exclamation
              mark (!)

          3.  Every RIPscrip command is preceded by the universal
              RIPscrip delimiter, vertical-bar (|)

          4.  Individual RIPscrip commands may be combined on the
              same line providing they are separated by the
              vertical bar delimiter.

          5.  RIPscrip commands or command lines may be split across
              multiple lines with a backslash (\) just before each
              split.  This helps RIPscrip commands conform to right
              margins and escape word wrapping.  An example:

                   !|c02|L02030405|P0901020102010201020102\
                   0102010201020102

          6.  RIPscrip must allow for normal text to be inter-mixed
              with RIPscrip commands.  If unrecognized text appears
              after a RIPscrip command, on the same line, the text
              is ignored (the command is not ignored).  A line that
              does not begin with "!|" is considered raw text and is
              routed to the TTY text window (see "8" below).

          7.  RIPscrip makes provisions for a GRAPHICAL WINDOW and a
              TEXT WINDOW.  The Graphical Window is where all
              RIPscrip graphics appear.  the TEXT WINDOW is where
              raw text appears.  Raw Text includes ANSI color and
              cursor movement codes (a subset of VT-100 terminal
              emulation).

          8.  The vertical bar (|) of a RIPscrip command can be
              followed by an level number.  If the 1st character
              after (|) is a numeric digit (1-9), then that's the
              RIPscrip Command Level.  If the very 1st character is
              NOT a digit 1-9, then it is the command type character
              and the command is a Level-0 command.  If the 1st
              character is a digit 1-9, and the second character is
              also a digit, then that defines a sub-level of a
              RIPscrip level.  For example:

                 !|L ..... RIPscrip Level-0 Command "L"
                 !|1L .... RIPscrip Level-1 Command "L"
                 !|15L ... RIPscrip Level-1, sub-level 5 Command "L"

              Each of the above examples are unique commands not to
              be confused with each other.  You may continue the
              sub-levels up to a maximum level of 10 (eg,
              !|1234567890<cmd>").

          9.  Every RIPscrip command includes a command type
              character.  In Level-0 commands, this character
              immediately follows the vertical bar.  At all other
              levels, it follows the level digits.  The command type
              character may be any printable non-decimal-digit
              character.

         10.  Following the command type character are 0 or more
              parameters.  If the command requires a text-string, it
              is always the LAST parameter.  Numeric parameters DO
              NOT have any delimiters (commas, dashes, spaces,
              etc).  A variable width numeric parameter may be used
              as the last parameter.  This allows for maximum
              efficiency.  Numbers are represented in base-36.  This
              compacts numbers down to roughly 3/5 of their decimal
              form.  This numbering system, technically called
              "Hexa-Tri-Decimal", has affectionately been dubbed
              "MegaNums".  Unlike Hexadecimal which uses 0-9, A-F,
              MegaNums take advantage of the entire alphabet, using
              characters 0-9 and A-Z.

         11.  An exclamation mark (!) or vertical bar (|) character
              can appear in a RIPscrip text parameter by preceding
              it with a backslash(\).  A literal backslash is
              represented with a double-backslash (\\).

         12.  A RIPscrip sequence CAN begin in a column other than
              column #0, if the exclamation mark introducer is
              replaced with a CTRL-A (Start of Header SOH) character,
              or CTRL-B (STX character).  Since 99.9% of all BBS'es do
              not allow Users to enter most control characters, users
              will be unable to begin RIPscrip sequences in the middle
              of a command line.  Only the Host should be able to do
              this.  This prevents people from cluttering
              teleconference, or other areas of a Host with spurious
              RIPscrip sequences.





     =====================================================================
     ==                         ANSI SEQUENCES                          ==
     =====================================================================


     RIPscrip predominantly uses non-ANSI command sequences.  In a couple
     of situations though, an ANSI sequence is allowed to perform a
     specific function.  There are currently three separate ANSI sequences
     defined in the RIPscrip protocol to perform various actions.  They
     are as follows:



          ESC [ ! ...... Query RIPscrip version number.  RIPterm will
                         respond with RIPSCRIPxxyyzz where xx is equal
                         to the major version number (zero padded), yy
                         is equal to the minor version number (zero
                         padded), and zz equals the revision code (also
                         zero padded).  For v1.51.00, the returned
                         sequence would be RIPSCRIP015100.  Another
                         example, v1.23.45 would return RIPSCRIP012345.

          ESC [ 0 ! .... Same as ESC [ ! (see above)

          ESC [ 1 ! .... Disables all RIPscrip processing.  Any RIPscrip
                         sequences are interpretted as raw text.

          ESC [ 2 ! .... Enabled RIPscrip processing.  Any RIPscrip
                         sequences will be parsed and processed.






     =====================================================================
     ==                    RIPscrip COMMAND REFERENCE                   ==
     =====================================================================

     The remainder of this document details the RIPscrip command set.
     Each command has these aspects:

         SYMBOL - the symbolic constant that is referenced in the
                  RIPscrip API Library code.  This is  the universal
                  name for the command.

          LEVEL - The Command Level.  Sub-levels are represented
                  with decimal points (eg, 1.3.5 for Level-1,
                  Sub-level 3, Sub-Sub-level 5).  This is for
                  discussion purposes only.  The decimal points
                  are never part of the actual command.

        COMMAND - The command type character identifying the
                  command

      ARGUMENTS - The arguments or parameters for the command.
                  Commands that do not require any arguments
                  after the command type character are shown
                  here as "<none>".  Each argument is shown in
                  the order it appears in the command, and is
                  represented by a name.  If an argument is
                  numeric, it is followed by a width specifier
                  indicating how many MegaNum digits the
                  argument consists of.  (eg, ":2" means a
                  2-digit MegaNum, or a value between 0 and
                  1295).  If an argument does not have a width
                  specifier, it is by default a text argument,
                  and should be the last argument on the line.
                  If a command is variable length (see POLYGON),
                  then it will appear with ellipses (...)

         FORMAT - This represents the format of the command, with
                  the starting "!|", the level digits, the
                  command type character, and the argument list,
                  with the argument names in angle brackets.
                  (These arguments are spaced apart, but these
                  spaces never appear in the physical commands.)

        EXAMPLE - An actual example of the RIPscrip command.

     DRAW COLOR - If YES, then this command uses or affects the
                  current Drawing Color.

     LINE PATRN - If YES, then this command uses or affects the
                  current Line Style Pattern.

     LINE THICK - If YES, then this command uses or affects the
                  current Line Style Thickness

     FILL COLOR - If YES, then this command uses or affects the
                  current Fill Color.

     FILL PATRN - If YES, then this command uses or affects the
                  current Fill Pattern.

     WRITE MODE - If YES, then this command will take advantage
                  of the current Write Mode (eg, COPY, or XOR).

     FONT SIZES - If YES, then this command uses or affects the
                  current Font Size.





     ---------------------------------------------------------------------
     Define the size and location of the TTY Text Window
     ---------------------------------------------------------------------
               Symbol: RIP_TEXT_WINDOW
                Level: 0
              Command: w
            Arguments: x0:2, y0:2, x1:2, y1:2, wrap:1, size:1
               Format: !|w <x0> <y0> <x1> <y1> <wrap> <size>
              Example: !|w00001B0M10
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command specifies the dimensions of the virtual TTY window that
     will display all ASCII/ANSI (non-RIPscrip) data coming across the
     connection.  (x0,y0) defines the upper-left corner of the window in
     text-based character-cell coordinates.  (x1,y1) defines the
     lower-right corner of the window (inclusive).  There may be two
     simultaneous windows on the screen, one for TTY text, and one for the
     display of RIPscrip graphics (a viewport), and they may overlap.

     Bytes received over the modem are first checked for RIPscrip
     commands.  All bytes that don't conform to the RIPscrip syntax are
     treated as ANSI/ASCII and displayed in the TTY window (if defined).
     User keystrokes that are echoed by the BBS would also appear in the
     text window by this scheme.

     The text window may be made invisible, ignoring all non-RIPscrip
     bytes, by setting all RIP_TEXT_WINDOW parameters to zero (0).  The X
     and Y parameters ranges vary depending on the setting of the <size>
     parameter which governs the font size used for the output text. Valid
     settings for the <size> parameter and the ranges for X/Y values are
     as follows:

          size   Font Size    X Range   Y Range
          ---------------------------------------
           0       8x8         0-79      0-42
           1       7x8         0-90      0-42
           2       8x14        0-79      0-24
           3       7x14        0-90      0-24
           4       16x14       0-39      0-24

     The <wrap> parameter applies to both the horizontal and vertical
     dimensions.  If <wrap> is set to 1, then any text that extends beyond
     the right margin of the window will wrap to the next line of the
     window, scrolling the window up if necessary.  If <wrap> is 0, then
     any text going beyond the right margin is truncated and no scrolling
     is performed; the cursor remains at the right margin.

     NOTE:  If the text window currently being defined is identical
            to the currently defined text window, the cursor will
            not be relocated to the upper-left corner of the window.
            The only aspect of the text window that can be different
            and still be deemed "identical" is the <wrap> parameter.
            For the current and new text windows to be considered
            identical, the parameters <x0>, <y0>, <x1>, <y1> and
            <size> must be the same.





     ---------------------------------------------------------------------
     Define the size and location of the Graphics Window
     ---------------------------------------------------------------------
               Symbol: RIP_VIEWPORT
                Level: 0
              Command: v
            Arguments: x0:2, y0:2, x1:2, y1:2
               Format: !|v <x0> <y0> <x1> <y1>
              Example: !|v00002E1M
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command defines the (X,Y) pixel boundaries of the RIPscrip
     graphics window, which will contain all RIPscrip graphics output.
     ASCII/ANSI text will be displayed in the virtual TTY window defined
     by the RIP_TEXT_WINDOW command above.  (x0,y0) defines the upper-left
     corner of the graphics viewport, and (x1,y1) defines the lower-right
     corner (inclusive).  The viewport may be disabled, so RIPscrip
     graphics commands are ignored, by setting all parameters to zero (0).

     Graphics displayed in the viewport is "truncated" at this rectangular
     border, meaning if a circle would normally extend outside one of the
     borders, it will be chopped, only displaying the portion of the
     circle that is contained inside the viewport boundaries.

     Coordinates are specified based on a 640x350 pixel resolution, meaning
     X can be anywhere from 0 - 639, and Y can be anywhere from 0 - 349.
     x0 must be less than x1 and y0 must be less than y1 unless all
     parameters are set to zero, indicating that the graphics window is
     disabled.





     ---------------------------------------------------------------------
     Reset & Clear Graphics and Text Windows to full screen
     ---------------------------------------------------------------------
               Symbol: RIP_RESET_WINDOWS
                Level: 0
              Command: *
            Arguments: <none>
               Format: !|*
              Example: !|*
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command will set the Text Window to a full 80x43 EGA hi-res text
     mode, place the cursor in the upper left corner, clear the screen,
     and zoom the Graphics Window to full 640x350 EGA screen.  Both
     windows are filled with the current graphics background color.  Also,
     all Mouse Regions are deleted and the Clipboard is erased.  A system
     might use this function before entering a text only mode that does
     not support RIP commands.  This command will also restore the default
     16-color RIP palette (see RIP_SET_PALETTE below).





     ---------------------------------------------------------------------
     Clears the Text Window to the current background color
     ---------------------------------------------------------------------
               Symbol: RIP_ERASE_WINDOW
                Level: 0
              Command: e
            Arguments: <none>
               Format: !|e
              Example: !|e
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This clears the TTY text window to the current graphics background
     color and positions the cursor in the upper-left corner of the
     window.  If the text window is inactive, then this command is
     ignored.  If the text and graphics windows overlap, then this command
     will clear the overlapping portion also.





     ---------------------------------------------------------------------
     Clears the Graphics Window to the current background color
     ---------------------------------------------------------------------
               Symbol: RIP_ERASE_VIEW
                Level: 0
              Command: E
            Arguments: <none>
               Format: !|E
              Example: !|E
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command clears the Graphics Viewport to the current graphics
     background color.  If the graphics viewport is not active (if the
     boundaries are 0,0,0,0), then this command is ignored.  If the text
     and graphics windows overlap, then this command will clear the
     overlapping portion also.





     ---------------------------------------------------------------------
     Move the Text (TTY) cursor to given row & column in the text window
     ---------------------------------------------------------------------
               Symbol: RIP_GOTOXY
                Level: 0
              Command: g
            Arguments: x:2, y:2
               Format: !|g <x> <y>
              Example: !|g0509
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command sets the position of the text cursor in the TTY Text
     window, if it is active.  If inactive (if the dimensions are
     0,0,0,0), then this command is ignored.  This command is equivalent
     to the ANSI/VT-100 command goto x/y, <Esc>[x;yH, except that the
     coordinates of that ANSI command are 1-based and the coordinates of
     this RIPscrip command are 0-based.





     ---------------------------------------------------------------------
     Move the cursor to the Upper-Left corner of the Text Window
     ---------------------------------------------------------------------
               Symbol: RIP_HOME
                Level: 0
              Command: H
            Arguments: <none>
               Format: !|H
              Example: !|H
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command positions the text cursor to the upper-left corner in
     the TTY Text Window, if it is active.





     ---------------------------------------------------------------------
     Erase the current text line from the cursor to the end of line
     ---------------------------------------------------------------------
               Symbol: RIP_ERASE_EOL
                Level: 0
              Command: >
            Arguments: <none>
               Format: !|>
              Example: !|>
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command will erase the current text line in the TTY text window
     from the current cursor location (inclusive) to the end of the line.
     The erased region is filled with the current graphics background
     color.  This differs from the ANSI command ESC[K which clears the
     area with the current ANSI background color.





     ---------------------------------------------------------------------
     Set the current drawing color for graphics primitives
     ---------------------------------------------------------------------
               Symbol: RIP_COLOR
                Level: 0
              Command: c
            Arguments: color:2
               Format: !|c <color>
              Example: !|cA
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command sets the color for drawing lines, circles, arcs,
     rectangles, and other graphics primitives, as well as the color for
     drawing grahics-text from the RIP_TEXT class of commands (not from
     ASCII/ANSI text).  This command does not affect Fill colors or Fill
     Patterns (see below).  It does affect the borders of graphic objects,
     for example the border of an ellipse drawn with the RIP_FILLED_OVAL
     command.  (The interior of the ellipse would be drawn according to
     the most recent RIP_FILL_STYLE command.)

     This command chooses one of the colors of the 16-color RIP palette
     defined by the RIP_SET_PALETTE command.  Here is the default 16-color
     RIP palette:

          VALUE ... COLOR
          -------------------------------------
            00  ... Black (00 is always the background color)
            01  ... Blue
            02  ... Green
            03  ... Cyan
            04  ... Red
            05  ... Magenta
            06  ... Brown
            07  ... Light Gray
            08  ... Dark Gray
            09  ... Light Blue
            0A  ... Light Green
            0B  ... Light Cyan
            0C  ... Light Red
            0D  ... Light Magenta
            0E  ... Yellow
            0F  ... White





     ---------------------------------------------------------------------
     Set the 16-color RIP palette from the master 64-color EGA palette
     ---------------------------------------------------------------------
               Symbol: RIP_SET_PALETTE
                Level: 0
              Command: Q
            Arguments: c1:2, c2:2, ... c16:2
               Format: !|Q <c1> <c2> ... <c16>
              Example: !|Q000102030405060708090A0B0C0D0E0F
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command modifies the 16-color RIP palette by choosing from the
     64 colors in the master EGA palette.  This allows you to alter the
     colors in your RIPscrip graphics scenes.  Once a Set Palette command
     is processed, any colors on the screen that had their corresponding
     palette entries changed will instantly switch to the new color set.
     You may obtain color "cycling" effects by using this command.  The
     default 16-color RIP palette is always restored when a
     RIP_RESET_WINDOWS command is encountered.  The default 16-color RIP
     palette is as follows:

                           MASTER
          16-COLOR         64-COLOR
          RIP PALETTE      EGA PALETTE
          COLOR-CODE       COLOR-CODE    COLOR
          -------------------------------------------------------
              00            0  (00)      Black
              01            1  (01)      Blue
              02            2  (02)      Green
              03            3  (03)      Cyan
              04            4  (04)      Red
              05            5  (05)      Magenta
              06            7  (06)      Brown
              07            20 (0K)      Light Gray
              08            56 (1K)      Dark Gray
              09            57 (1L)      Light Blue
              0A            58 (1M)      Light Green
              0B            59 (1N)      Light Cyan
              0C            60 (1O)      Light Red
              0D            61 (1P)      Light Magenta
              0E            62 (1Q)      Yellow
              0F            63 (1R)      White

     Color 00 of the 16-color RIP palette is always the background color
     (which is typically Black, or color 00 of the 64-color EGA palette).






     ---------------------------------------------------------------------
     Set one color of the 16-color RIP palette from the Master Palette
     ---------------------------------------------------------------------
               Symbol: RIP_ONE_PALETTE
                Level: 0
              Command: a
            Arguments: color:2 value:2
               Format: !|a <color> <value>
              Example: !|a051B
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command modifies one color in the 16-color RIP palette.  The
     Color number is sent along with the a color value from the Master
     Color Palette to set the new color to.  The color <value> must be
     in the range of 0-63 to allow access to the 64 colors in the master
     EGA palette.  This allows you to alter the colors in your RIPscrip
     graphics scenes.  Once a Set One Palette command is processed, any
     colors on the screen that correspond to the <color> number will be
     changed instantly to the new color value.  You may obtain color
     "cycling" effects by using this command.  The default 16-color RIP
     palette is always restored when a RIP_RESET_WINDOWS command is
     encountered.  The default 16-color RIP palette is as follows:

                           MASTER
          16-COLOR         64-COLOR
          RIP PALETTE      EGA PALETTE
          COLOR-CODE       COLOR-CODE    COLOR
          -------------------------------------------------------
              00            0  (00)      Black
              01            1  (01)      Blue
              02            2  (02)      Green
              03            3  (03)      Cyan
              04            4  (04)      Red
              05            5  (05)      Magenta
              06            7  (06)      Brown
              07            20 (0K)      Light Gray
              08            56 (1K)      Dark Gray
              09            57 (1L)      Light Blue
              0A            58 (1M)      Light Green
              0B            59 (1N)      Light Cyan
              0C            60 (1O)      Light Red
              0D            61 (1P)      Light Magenta
              0E            62 (1Q)      Yellow
              0F            63 (1R)      White

     Color 00 of the 16-color RIP palette is always the background color
     (which is typically Black, or color 00 of the 64-color EGA palette).





     ---------------------------------------------------------------------
     Set Drawing Mode for graphics primitives
     ---------------------------------------------------------------------
               Symbol: RIP_WRITE_MODE
                Level: 0
              Command: W
            Arguments: mode:2
               Format: !|W <mode>
              Example: !|W00
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command sets the current drawing mode for most of the graphics
     primitives:

          mode = 00 ... Normal drawing mode (overwrite)
               = 01 ... XOR (complimentary) mode

     In normal mode, things are drawn in the current drawing color over
     top of whatever is in the graphics viewport.  This is the typical
     mode of operation in a GUI environment.

     In the XOR mode, instead of changing each pixel to the current
     drawing color, the pixel is inverted (black changes to white, red to
     green, etc.).  Drawing the same item a second time erases it
     completely.  This mode is useful for drawing something temporarily,
     or for animation.  The Rubber Band mode of most paint programs uses a
     mode like this.





     ---------------------------------------------------------------------
     Move the current drawing position to (X,Y)
     ---------------------------------------------------------------------
               Symbol: RIP_MOVE
                Level: 0
              Command: m
            Arguments: x:2, y:2
               Format: !|m <x> <y>
              Example: !|m0509
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command moves the current graphics drawing cursor to (x,y).  You
     could use this to draw text at a certain point, but you'd probably
     use RIP_TEXT_XY instead.  This command is primarily provided for
     future development which will make use of its ability to relocate the
     current drawing position without physically drawing anything.





     ---------------------------------------------------------------------
     Draw Text in current Font/Size/Color at current location
     ---------------------------------------------------------------------
               Symbol: RIP_TEXT
                Level: 0
              Command: T
            Arguments: text-string
               Format: !|T <text-string>
              Example: !|Thello world
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: YES

     This command displays text at the current location in the graphics
     window, as set with the RIP_MOVE command.  The text is also affected
     by the most recent settings of these commands:

          RIP_FONT_STYLE - font style (character set, direction, size)
          RIP_WRITE_MODE - drawing mode (normal or XOR)
          RIP_COLOR      - drawing color (from the 16-color RIP palette)

     The drawing position is placed at the end of the last character
     drawn.

     The current drawing position is set immediately to the right of the
     drawn text.  Subsequent Line, Circle or other such commands will not
     affect this position.  This provides a means so that you can quickly
     do another RIP_TEXT command (presumably in another color) at a later
     time and have the text show up immediately after the previous text.





     ---------------------------------------------------------------------
     Draw Text in current Font/Size/Color at specific location
     ---------------------------------------------------------------------
               Symbol: RIP_TEXT_XY
                Level: 0
              Command: @
            Arguments: x:2, y:2 and text-string
               Format: !|@ <x> <y> <text-string>
              Example: !|@0011hello world
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: YES

     This command is an efficient combination of RIP_MOVE and RIP_TEXT.
     The text is drawn at the specified location according to the same
     settings as apply to RIP_TEXT (see above).

     The current drawing position is set immediately to the right of the
     drawn text.  Subsequent Line, Circle or other such commands will not
     affect this position.  This provides a means so that you can quickly
     do another RIP_TEXT command (presumably in another color) at a later
     time and have the text show up immediately after the previous text.





     ---------------------------------------------------------------------
     Select the current Font Style, Orientation and Size
     ---------------------------------------------------------------------
               Symbol: RIP_FONT_STYLE
                Level: 0
              Command: Y
            Arguments: font:2, direction:2, size:2, res:2
               Format: !|Y <font> <direction> <size> <res>
              Example: !|Y01000400
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: YES

     This command sets the current font, direction and size for subsequent
     RIP_TEXT commands.

          FONT
          ---------------------------------------------------------
          00 ... Default 8x8 font (bit-mapped)
          01 ... Triplex Font (scalable)
          02 ... Small Font (scalable)
          03 ... Sans Serif Font (scalable)
          04 ... Gothic [old English] Font (scalable)

          DIRECTION
          ---------------------------------------------------------
          00 ... Horizontal direction
          01 ... Vertical direction

          SIZE
          ---------------------------------------------------------
          01 ... Normal, default size
          02 ... Magnification factor  2 ( x2)
          03 ... Magnification factor  3 ( x3)
          04 ... Magnification factor  4 ( x4)
          05 ... Magnification factor  5 ( x5)
          06 ... Magnification factor  6 ( x6)
          07 ... Magnification factor  7 ( x7)
          08 ... Magnification factor  8 ( x8)
          09 ... Magnification factor  9 ( x9)
          0A ... Magnification factor 10 (x10)

     NOTE:  The Default 8x8 font is bit-mapped and appears best when drawn
     with size=1.  If you use a size greater than one, the individual
     pixels making up the font are magnified, giving a jagged look.  This
     may or may not be a desirable effect.  The Scalable Fonts (1-4) are
     smooth scalable "vector" fonts.  The two byte <res> parameter is a
     RESERVED parameter that is intended for future development.





     ---------------------------------------------------------------------
     Draws a single pixel on the screen using current drawing color
     ---------------------------------------------------------------------
               Symbol: RIP_PIXEL
                Level: 0
              Command: X
            Arguments: x:2, y:2
               Format: !|X <x> <y>
              Example: !|X1122
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command will draw a single pixel in the current drawing color at
     the given (x,y) graphics position.  This command is included for
     completeness, but in practice it would be extremely inefficient to
     make much use of it.





     ---------------------------------------------------------------------
     Draw a line in the current color and line style/thickness
     ---------------------------------------------------------------------
               Symbol: RIP_LINE
                Level: 0
              Command: L
            Arguments: x0:2, y0:2, x1:2, y1:2
               Format: !|L <x0> <y0> <x1> <y1>
              Example: !|L00010A0E
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command will draw a line in the current drawing color, using the
     current line style, pattern and thickness.  The line is drawn from
     (x0,y0) to (x1,y1) in the graphics viewport.





     ---------------------------------------------------------------------
     Draw a rectangle in the current color and line style/thickness
     ---------------------------------------------------------------------
               Symbol: RIP_RECTANGLE
                Level: 0
              Command: R
            Arguments: x0:2, y0:2, x1:2, y1:2
               Format: !|R <x0> <y0> <x1> <y1>
              Example: !|R00010A0E
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command draws a rectangle in the current drawing color, using
     the current line style, pattern and thickness.  (x0,y0) and (x1,y1)
     are any two opposing corners of the rectangle.  If x0=x1 or y0=y1
     then the command will draw a single vertical or horizontal line.  The
     rectangle interior is not filled by RIP_RECTANGLE.





     ---------------------------------------------------------------------
     Draws a solid, filled rectangle using current fill color and pattern
     ---------------------------------------------------------------------
               Symbol: RIP_BAR
                Level: 0
              Command: B
            Arguments: x0:2, y0:2, x1:2, y1:2
               Format: !|B <x0> <y0> <x1> <y1>
              Example: !|B00010A0E
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command fills a rectangular region with the current fill color
     and pattern.  No border is drawn.





     ---------------------------------------------------------------------
     Draw a circle in the current color and line thickness (no style)
     ---------------------------------------------------------------------
               Symbol: RIP_CIRCLE
                Level: 0
              Command: C
            Arguments: x_center:2, y_center:2, radius:2
               Format: !|C <x_center> <y_center> <radius>
              Example: !|C1E180M
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws a circle in the current drawing color and line
     thickness.  The <radius> is in pixel units.  This command understands
     aspect ratios and will draw a truly circular circle instead of an
     oblong circle (ellipse) like on other graphics systems.  The aspect
     ratio is currently based on the EGA 640x350 resolution and is
     understood by both the GUI designer and the Terminal Program.  This
     command does not take advantage of line patterns, but does use the
     line thickness setting.  In other words, you can draw a circle with a
     thick or a thin border, but not a dashed or dotted border.





     ---------------------------------------------------------------------
     Draw an elliptical arc in the current color and line thickness
     ---------------------------------------------------------------------
               Symbol: RIP_OVAL
                Level: 0
              Command: O
            Arguments: x:2, y:2, st_ang:2, end_ang:2, x_rad:2, y_rad:2
               Format: !|O <x> <y> <st_ang> <end_ang> <x_rad> <y_rad>
              Example: 1E1A18003G150Z
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws an elliptical arc similar to the circular RIP_ARC
     command.  The center of the ellipse is (x,y) and the arc is
     drawn starting from <st_ang> and proceeding counterclockwise to
     <end_ang> (see RIP_ARC above for details).

     The X radius is half the full width of the ellipse, the Y radius is
     half the full height.  The ellipse is drawn according to the current
     line thickness, but the current line pattern has no effect.





     ---------------------------------------------------------------------
     Draws a filled ellipse using the current fill and drawing color
     ---------------------------------------------------------------------
               Symbol: RIP_FILLED_OVAL
                Level: 0
              Command: o
            Arguments: x_center:2, y_center:2, x_rad:2, y_rad:2
               Format: !|o <x_center> <y_center> <x_rad> <y_rad>
              Example: !|o1G2B0M0G
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws a complete filled ellipse on the screen.  The
     interior of the ellipse is drawn using the current fill pattern and
     fill color.  The outline of the ellipse is drawn using the current
     drawing color and line thickness.





     ---------------------------------------------------------------------
     Draw a circular arc in the current color and line thickness
     ---------------------------------------------------------------------
               Symbol: RIP_ARC
                Level: 0
              Command: A
            Arguments: x:2, y:2, start_ang:2, end_ang:2, radius:2
               Format: !|A <x> <y> <start_ang> <end_ang> <radius>
              Example: !|A1E18003G15
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws a circular arc, or a segment of a circle.  Drawing
     begins at <start_ang> and terminates at <end_ang>.  The angles are
     represented starting at zero for the 3 o'clock position and
     increasing counterclockwise through a full circle to 360:

                               90
                                |
                          180---|--- 0
                                |
                               270

     The arc drawing begins at the <start_angle> and continues counter-
     clockwise to the <end_angle>.  A full circle will be displayed if
     <start_ang>=0 and <end_ang>=360.  This command recognizes aspect
     ratios like the circle command does.  It does not take advantage of
     line patterns but does comply with line thickness.

     If both angles are equal, nothing is drawn.





     ---------------------------------------------------------------------
     Draw an Elliptical Arc
     ---------------------------------------------------------------------
               Symbol: RIP_OVAL_ARC
                Level: 0
              Command: V
            Arguments: x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
               Format: !|V <x> <y> <st_ang> <e_ang> <radx> <rady>
              Example: !|V1E18003G151Q
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws an elliptical arc, or a segment of an ellipse.
     Drawing begins at <st_ang> and terminates at <e_ang>.  The angles are
     represented starting at zero for 3 o'clock position and increasing
     counterclockwise through a full ellipse at 360 degrees:

                               90
                                |
                          180---|--- 0
                                |
                               270

     The arc drawing begins at the <st_ang> and continues counterclockwise
     to the <e_ang>.  A complete ellipsewill be displayed if <st_ang>=0
     and <e_ang>=360.  This command does not utilize "aspect ratios"
     because of the nature of an Ellipse.  It does not take advantage of
     line patterns but does comply with line thickness.





     ---------------------------------------------------------------------
     Draw a circular Pie Slice
     ---------------------------------------------------------------------
               Symbol: RIP_PIE_SLICE
                Level: 0
              Command: I
            Arguments: x:2, y:2, start_ang:2, end_ang:2, radius:2
               Format: !|I <x> <y> <start_ang> <end_ang> <radius>
              Example: !|I1E18003G15
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws a "pie slice".  The slice is circular.  It obeys
     all of the same commands as the Arc command described above.  The
     ends of the arc are connected to the Center-Point of the Arc with two
     straight lines.  These two lines converge at the Center-Point.  The
     interior of the Slice is filled with the current Fill Color and
     Pattern.  The exterior (outline) of the Slice is drawn using the
     current drawing color and line thickness.  The Line Pattern feature
     does not apply to this command.





     ---------------------------------------------------------------------
     Draw an Elliptical Pie Slice
     ---------------------------------------------------------------------
               Symbol: RIP_OVAL_PIE_SLICE
                Level: 0
              Command: i
            Arguments: x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
               Format: !|i <x> <y> <st_ang> <e_ang> <radx> <rady>
              Example: !|i1E18003G151Q
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: YES
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command draws an  "elliptical pie slice".  It obeys all of the
     same commands as the Elliptical Arc command described above.  The
     ends of the arc are connected to the Center-Point of the Arc with two
     straight lines.  These two lines converge at the Center-Point.  The
     interior of the Slice is filled with the current Fill Color and
     Pattern.  The exterior (outline) of the Slice is drawn using the
     current drawing color and line thickness.  The Line Pattern feature
     does not apply to this command.





     ---------------------------------------------------------------------
     Draw a custom "Bezier" curve
     ---------------------------------------------------------------------
               Symbol: RIP_BEZIER
                Level: 0
              Command: Z
            Arguments: x1:2 y1:2  x2:2 y2:2  x3:2 y3:2  x4:2 y4:2  cnt:2
               Format: !|Z <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4> <cnt>
              Example: !|Z0A0B0C0D0E0F0G0H1G
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command provides customizable Curves.  Four "control points" are
     used to create the shape of the curve.  The curves beginning point is
     at point (x1,y1) and it ends at (x4,y4).  Points (x2,y2) and (x3,y3)
     are not necessarily "on" the curve, but are used to "pull" the curve
     in their direction.  The diagram below indicates how points 2 and 3
     can be utilized to form the desired curve.  Note that points 2 and 3
     are not actually "on" the curve, but points 1 and 4 are.

                          X2

                         *****
                       **     ****
                      *           **            X4
                     *              **          *
                   X1                 *       **
                                       *    **
                                        ****

                                         X3

     NOTE: That points 2 and 3 are not actually "on" the curve, but points
           1 and 4 are.

     The last parameter of this command is the <cnt> parameter.  This
     determines how many "segments" the curve should be drawn in.  Each
     segment is in fact, a straight line.  The more segments you allow,
     the smoother the curve may be.  If a curve does not have a
     significant amount of "curviness" then a low "count" can improve
     performance of the curve drawing.  Bezier Curves use "floating point"
     math internally for its processing.  All paramters specified for this
     command are simple integers however.





     ---------------------------------------------------------------------
     Draws a polygon using the current color and line style/thickness
     ---------------------------------------------------------------------
               Symbol: RIP_POLYGON
                Level: 0
              Command: P
            Arguments: npoints:2, x1:2, y1:2, ... xn:2, yn:2
               Format: !|P <npoints> <x1> <y1> ... <xn> <yn>
              Example: !|P03010105090905
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command will draw a multi-sided closed polygon.  The polygon is
     drawn using the current drawing color, line pattern and thickness.
     The <npoints> parameter is between 2 and 512 and indicates how many
     (x,y) coordinate pairs will follow, which is also the number of sides
     of the polygon.  The polygon interior is not filled by RIP_POLYGON.

     The polygon is enclosed by the last vertex between xn,yn and x1,y1.
     In other words, you do not have to connect the end to the beginning -
     it is automatically done for you.





     ---------------------------------------------------------------------
     Draws a filled polygon, using drawing color, current fill settings
     ---------------------------------------------------------------------
               Symbol: RIP_FILL_POLY
                Level: 0
              Command: p
            Arguments: npoints:2, x1:2, y1:2, ... xn:2, yn:2
               Format: !|p <npoints> <x1> <y1> ... <xn> <yn>
              Example: !|p03010105050909
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: YES
      Uses Font Sizes: NO

     This command is identical to RIP_POLYGON, except that the interior of
     the polygon is filled with the current fill color and fill pattern.
     The actual outline of the polygon is drawn using the current drawing
     color, line pattern and thickness.

     NOTE:  You will get unusual effects if the lines of the polygon
     overlap, creating a polygon with internal "gaps".  (The rule is
     this:  regions that are "inside" the polygon an even number of times
     due to overlap are NOT filled.)  The interior fill does not utilize
     Write Mode, but the outline of the polygon does.





     ---------------------------------------------------------------------
     Flood Fills a given area of the screen with the current fill settings
     ---------------------------------------------------------------------
               Symbol: RIP_FILL
                Level: 0
              Command: F
            Arguments: x:2, y:2, border:2
               Format: !|F <x> <y> <border>
              Example: !|F25090F
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command performs a "flood fill" emanating from the given <x,y>
     point.  The fill "oozes" in all directions up to <border> color, but
     the border itself is not changed.  Whatever is inside the border
     that's not the border color gets changed to the current fill color
     and fill pattern.  If the border color does not completely enclose
     the <x,y> point, the fill will continue to the edges of the viewport.





     ---------------------------------------------------------------------
     Defines a line style and thickness
     ---------------------------------------------------------------------
               Symbol: RIP_LINE_STYLE
                Level: 0
              Command: =
            Arguments: style:2, user_pat:4, thick:2
               Format: !|= <style> <user_pat> <thick>
              Example: !|=01000001
      Uses Draw Color: NO
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command establishes the current line pattern and thickness for
     many subsequent graphics primitive commands.  There are four built-in
     line styles plus provisions for custom line patterns.


          STYLE
          =================================================
            00 ... Normal, Solid Line
            01 ... Dotted Line
            02 ... Centered Line
            03 ... Dashed Line
            04 ... Custom Defined line (see about <user_pat> below)

          THICK (these are the only available settings)
          =================================================
            01 ... Lines are 1 pixel wide
            03 ... Lines are 3 pixels wide

     If the <style> is set to a value of 4 (custom pattern), then the
     <user_pat> parameter is used as a 16-bit representation of the pixels
     in the line pattern.  For example:


              repeating                                            Mega-
           <---pattern---->   Binary coding       Hex    Decimal   num

           - - - - - - - -    1010101010101010    AAAA   43690     0XPM

           ----    ----       1111000011110000    F0F0   61680     1BLC


     So, the most-significant-bit of <user_pat> is toward the starting
     point of the line or border that uses this fill pattern.  If the
     <style> parameter is not 4, then the <user_pat> parameter is ignored.





     ---------------------------------------------------------------------
     Sets the current fill style (predefined patterns), and fill color
     ---------------------------------------------------------------------
               Symbol: RIP_FILL_STYLE
                Level: 0
              Command: S
            Arguments: pattern:2, color:2
               Format: !|S <pattern> <color>
              Example: !|S050F
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command defines the current fill pattern and fill color for use
     in subsequent graphics fill operations.  There are twelve (12)
     predefined fill patterns.  They are:

          PATTERN DESCRIPTION
          ==============================================================
            00    Fill with background color (color #0)
            01    Solid Fill (fill color)
            02    Line Fill ................. ----------- (thick lines)
            03    Light Slash Fill .......... /  /  /  /  (thin lines)
            04    Normal Slash Fill ......... // // // // (thick lines)
            05    Normal Backslash Fill ..... \\ \\ \\ \\ (thick lines)
            06    Light Backslash Fill ...... \  \  \  \  (thin lines)
            07    Light Hatch Fill .......... ########### (thin lines)
            08    Heavy Cross Hatch Fill .... XXXXXXXXXXX (thin lines)
            09    Interleaving Line Fill .... +-+-+-+-+-+ (thin lines)
            0A    Widely spaced dot fill .... . : . : . : (pixels only)
            0B    Closely spaced dot fill ... ::::::::::: (pixels only)

     The <color> parameter is the fill color for subsequent fill commands.
     The "active" pixels of the pattern become this color.  The "inactive"
     pixels become the current background color (color 00, typically
     black).  Fill pattern 00 will set the entire fill area to the
     background color.  (In this special case, the fill color doesn't
     matter.)





     ---------------------------------------------------------------------
     Sets a user-definable fill pattern (custom) and fill color
     ---------------------------------------------------------------------
               Symbol: RIP_FILL_PATTERN
                Level: 0
              Command: s
            Arguments: c1:2 c2:2 c3:2 c4:2 c5:2 c6:2 c7:2 c8:2 color:2
               Format: !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <color>
              Example: !|s11223344556677880F
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command allows you to specify a user-defined, custom Fill
     Pattern.  This pattern supersedes the predefined patterns of
     RIP_FILL_STYLE.  A custom fill pattern is an 8x8 pixel array defining
     which pixels should be drawn in the current fill color (as set by the
     <color> parameter here).  The other pixels in the fill area are set
     to the current background color (color 00, typically black).

     Each of the eight parameters of this command, <c1> through <c8>
     represent bit-patterns for a line of the 8x8 pixel array.  Each line
     is comprised of 8 pixels.  The value of each parameter is the binary
     representation of these 8 pixels as follows:

          bit   7   6   5   4   3   2   1   0
              +-------------------------------+
          c1  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c2  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c3  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c4  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c5  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c6  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c7  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+
          c8  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
              +-------------------------------+

     So, c1 is the top, and the most-significant bit is to the left.

     NOTE: The RIP_FILL_STYLE (predefined fill patterns) and this
     RIP_FILL_PATTERN (custom fill patterns) completely override one
     another's effects.





     ---------------------------------------------------------------------
     Defines a rectangular "hot" Mouse Region on screen
     ---------------------------------------------------------------------
               Symbol: RIP_MOUSE
                Level: 1
              Command: M
            Arguments: num:2  x0:2 y0:2  x1:2 y1:2  clk:1 clr:1 res:5 text
               Format: !|1M <num> <x0><y0> <x1><y1> <clk><clr><res> <text>
              Example: !|1M00001122331100000host command^M
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command ties together three things:

          A region on the screen
          A mouse-click event
          A string of text to be transmitted by the terminal.

     This command defines a rectangular region on the screen that functions
     as a "hot" mouse area.  If the user clicks the [left] mouse button
     while pointing inside the region, then the terminal must transmit the
     <text> string to the Host.  The (x0,y0) parameter MUST be the
     upper-left corner, and (x1,y1) MUST be the lower-right corner of the
     region.

     The <clk> parameter, if 1, indicates that the region should be
     visibly inverted while the mouse button is down.  This offers visual
     feedback.  If <clk> is 0, the region will not be inverted while
     clicked.

     The <clr> parameter, if 1, will physically zoom the text window to
     full screen size and clear the screen.  This is useful if the <text>
     parameter instructs the host to enter an area of the System that
     doesn't support RIPscrip graphics.

     The <text> parameter is a Host command that gets sent when the field
     is clicked.  You may use a caret (^) to represent control characters,
     (eg, ^M for carriage return, ^G, ^C, etc).

     NOTE: You are limited to a maximum of 128 Mouse Regions.  In addition,
           the 5-byte <res> parameter is RESERVED FOR FUTURE USE, and
           should be set to zeros (00000).





     ---------------------------------------------------------------------
     Destroys all previously defined "hot" Mouse Regions
     ---------------------------------------------------------------------
               Symbol: RIP_KILL_MOUSE_FIELDS
                Level: 1
              Command: K
            Arguments: <none>
               Format: !|1K
              Example: !|1K
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command will "forget" all Mouse Regions.  Use it at the beginning
     of each Scene, so that one scene's Mouse Regions don't get used in
     another.





     ---------------------------------------------------------------------
     Define a rectangular Text Region
     ---------------------------------------------------------------------
               Symbol: RIP_BEGIN_TEXT
                Level: 1
              Command: T
            Arguments: x1:2, y1:2, x2:2, y2:2, res:2
               Format: !|1T <x1> <y1> <x2> <y2> <res>
              Example: !|1T00110011
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command defines a rectangular portion of the graphics viewport
     that is to display text, usually a long stream of text.  Following
     this command should be a number of RIP_REGION_TEXT commands with the
     text to be displayed.  The RIP_END_TEXT terminates this stream of
     text, something like this:

          RIP_BEGIN_TEXT
             RIP_REGION_TEXT
             RIP_REGION_TEXT
             RIP_REGION_TEXT
             :
             RIP_REGION_TEXT
          RIP_END_TEXT

     There must be at least one RIP_REGION_TEXT command in between the
     header and the footer.  There may be as many as needed.

     These commands ignore the current font "direction"; all text is
     always displayed horizontally.

     NOTE:  The "res" parameter is two bytes wide and is RESERVED for
            future use.





     ---------------------------------------------------------------------
     Display a line of text in the rectangular Text Region
     ---------------------------------------------------------------------
               Symbol: RIP_REGION_TEXT
                Level: 1
              Command: t
            Arguments: justify:1 and text-string
               Format: !|1t <justify> <text-string>
              Example: !|1t1This is a text line to be justified
      Uses Draw Color: YES
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: YES
      Uses Font Sizes: YES

     A number of these commands may come sandwiched between the
     RIP_BEGIN_TEXT and RIP_END_TEXT commands.  The <text-string> is
     already word-wrapped in such a way that it will fit inside the
     rectangular region based on the current font, font size, and drawing
     color.

     There are two possible settings for the <justify> parameter:

          0 ... Don't right/left justify.  Left-justify only

          1 ... Perform right/left margin justification of this line
                of text except for the last line of a paragraph and
                sets of indented lines.

     If a text line falls off the bottom of the region, it is discarded --
     the rectangular Text Region does not scroll.





     ---------------------------------------------------------------------
     End a rectangular Text Region
     ---------------------------------------------------------------------
               Symbol: RIP_END_TEXT
                Level: 1
              Command: E
            Arguments: <none>
               Format: !|1E
              Example: !|1E
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command indicates the end of a formatted text block.  Only one
     of these "end" commands is necessary for each block.





     ---------------------------------------------------------------------
     Copies a rectangular screen image onto the Clipboard (as an Icon)
     ---------------------------------------------------------------------
               Symbol: RIP_GET_IMAGE
                Level: 1
              Command: C
            Arguments: x0:2, y0:2, x1:2, y1:2, res:1
               Format: !|1C <x0> <y0> <x1> <y1> <res>
              Example: !|1C001122330
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command instructs the terminal program to copy the rectangular
     region defined by (x0,y0) to (x1,y1) onto an internal Clipboard for
     future use.  This combined with the Paste Clipboard command can
     provide an extremely powerful and efficient mechanism to avoid
     baud-rate bandwidth limitations.  The (x0,y0) parameter MUST specify
     the upper-left corner of the region and the (x1,y1) parameter MUST
     specify the lower-right corner.  If the indicated coordinates are in
     anyway invalid, the command is ignored.  The Clipboard is completely
     overwritten by this command (the previous contents are lost).

     NOTE: The <res> parameter is RESERVED FOR FUTURE USE and should be
           set to zero.





     ---------------------------------------------------------------------
     Pastes the clipboard (Icon) contents onto the screen
     ---------------------------------------------------------------------
               Symbol: RIP_PUT_IMAGE
                Level: 1
              Command: P
            Arguments: x:2, y:2, mode:2, res:1
               Format: !|1P <x> <y> <mode> <res>
              Example: !|1P0011010
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command takes the contents of the Clipboard (if any) and pastes
     the image onto the screen starting at the upper-left corner of the
     image of (x,y).  If the right edge of the image would go off-screen,
     the paste command is ignored.  The Height and Width of the clipboard
     image is recorded on the Clipboard, so this command doesn't need to
     supply it.

     The <mode> parameter defines "how" the image will be pasted on the
     screen:

         MODE DESCRIPTION
         ==============================================================
           00 Paste the image on-screen normally                 (COPY)
           01 Exclusive-OR  image with the one already on screen (XOR)
           02 Logically OR  image with the one already on screen (OR)
           03 Logically AND image with the one already on screen (AND)
           04 Paste the inverse of the image on the screen       (NOT)

     NOTE: The 1-byte <res> parameter is RESERVED FOR FUTURE USE and
           should be set to zero.





     ---------------------------------------------------------------------
     Writes the contents of the Clipboard (Icon) to disk
     ---------------------------------------------------------------------
               Symbol: RIP_WRITE_ICON
                Level: 1
              Command: W
            Arguments: res:1, filename
               Format: !|1W <res> <filename>
              Example: !|1W0filename.icn
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command takes the contents of the Clipboard and writes it to a
     disk file.  This Icon file can be loaded later with a RIP_LOAD_ICON
     command and stamped on the screen.

     The command instructs the terminal to store an Icon on the terminal's
     disk drive, or on some appropriate storage media.  Path or
     subdirectory information is not allowed in the filename portion of
     the command.  If the clipboard is nonexistent (ie, at the beginning
     of a scene), this command is ignored.  If an Icon by the same name
     already exists on disk, it is overwritten.

     NOTE: The <res> parameter is RESERVED FOR FUTURE USE and should be
           set to zero.





     ---------------------------------------------------------------------
     Loads and displays a disk-based Icon to the screen
     ---------------------------------------------------------------------
               Symbol: RIP_LOAD_ICON
                Level: 1
              Command: I
            Arguments: x:2, y:2, mode:2, clipboard:1, res:2, filename
               Format: !|1I <x> <y> <mode> <clipboard> <res> <filename>
              Example: !|1I001101010button.icn
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command instructs the terminal to read an Icon from disk and
     display it at the given upper-left (x,y) location.  If the width or
     height of the Icon would make it go off the right or left edge of the
     screen, the Icon will not be displayed.  The <mode> parameter defines
     the modes in which the Icon will be displayed on the screen.  The
     modes are identical to the RIP_PUT_IMAGE command, and are as follows:

     The .ICN file extension does not need to be included as part of the
     filename.  If omitted, it will automatically be appended to the
     filename.  If an extension is provided, it will be used verbatim.

         Mode Description
         ==============================================================
           00 Paste the image on-screen normally                 (COPY)
           01 Exclusive-OR  image with the one already on screen (XOR)
           02 Logically OR  image with the one already on screen (OR)
           03 Logically AND image with the one already on screen (AND)
           04 Paste the inverse of the image on the screen       (NOT)

     If the <clipboard> parameter is 1, then not only is the image pasted
     on screen, but it is also copied into the Clipboard.  If 0, it's
     simply pasted on the screen.

     The <filename> parameter must not contain any subdirectory or path
     information and must specify a valid Icon file name.  If the Icon
     cannot be located or an error occurs on the disk, then a box should
     be displayed on screen indicating that the given Icon File could not
     be loaded.  This visual prompt indicates that something is amiss to
     the end-user.

     NOTE: The 2-byte <res> parameter is RESERVED FOR THE FUTURE and
           unlike many other previously mentioned reserved parameters,
           should be set to "10".





     ---------------------------------------------------------------------
     Button Style Definition
     ---------------------------------------------------------------------
               Symbol: RIP_BUTTON_STYLE
                Level: 1
              Command: B
            Arguments: wid:2 hgt:2 orient:2 flags:4 size:2 dfore:2
                       dback:2 bright:2 dark:2 surface:2 grp_no:2 flags2:2
                       uline_col:2 corner_col:2 res:6
               Format: !|1B <wid> <hgt> <orient> <flags> <bevsize> <dfore>
                       <dback> <bright> <dark> <surface> <grp_no> <flags2>
                       <uline_col> <corner_col> <res>
              Example: !|1B0A0A010274030F080F080700010E07000000
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This RIPscrip command is probably one of the most complex in the
     entire protocol.  It defines how subsequent RIP_BUTTON commands will
     be interpretted.  The purpose of this command is to define what a
     Button is and how they operate.  Buttons can have many different
     configurations, flags, and styles.  With the diversity of modes that
     the Button can take on, complexity is a necessary evil.

     This command does not actually do anything visibly on the screen.
     Simply put, this creates an internal definition for the Button mode
     which will be used with RIP_BUTTON commands after the definition is
     created.

     Every Button can have an optional text label.  It can appear in
     several different locations compared to the Button itself.  This is
     specified in the <orient> parameter.  The actual text of the label is
     not specified with this command, it is specified when you actually
     create a Button (see RIP_BUTTON below).  The value that <orient> can
     be is as follows:

          Value     Description of Orientation
          ===================================================
          00        Display Label above of Button
          01        Display Label to the Left of Button
          02        Display Label in the center of the Button
          03        Display Label to the Right of Button
          04        Display Label beneath the Button


     The <hgt> and <wid> parameters represent the fixed height and width of
     the Button (applies only to Plain Buttons).  If both values are
     greater than zero, then this will represent the actual size of the
     Button (its dimensions are not specified by the RIP_BUTTON command).
     If both of these are set to zero, then the actual RIP_BUTTON command
     will specify the size of the particular Button (dynamic sizing).

     The <bevsize> parameter is only used if the Bevel flag is specified.
     When active, this parameter will determine how many pixels thick the
     bevel should be.  This may be any value greater or equal to zero.

     There are a large number of flag values that can be combined to
     achieve a great many effects.  There are two flag parameters for the
     RIP_BUTTON_STYLE command, <flags> and <flags2>.  They are detailed in
     the two tables that follow in this Section.  You may combine any of
     the flags in the first table together simply by adding the "Value" of
     each one together and representing that number as a MegaNum.  See the
     Section in this manual for a "Table of MegaNums".

     The <dfore> and <dback> parameters are used with the text label.  The
     <dfore> parameter is the foreground color for the text.  It is always
     used to determine the color of the text label.  The <dback> color is
     the color of the dropshadow (if any).  This parameter is only used
     when you have specified the "Dropshadow" flag in the <flags>
     parameter (see below).

     The <bright>, <dark> and <surface> parameters are used with Plain
     Buttons and with the Special Effects styles (see <flags> below).
     These colors represent the hilighted color, the shadowed color, and
     the regular surface color that is used in Special Effects.  Typical
     color combinations for these colors might be White, Dark-Gray and
     Light-Gray respectively for a "chiseled steel" appearance.  Each of
     these values can contain a two-digit value representing any valid
     color code that may be used in the RIP_COLOR command.

     In addition to the special effects colors, are two additional colors
     that can be used, <uline_color> which is used for the color of the
     underline (in the text label), and <corner_color> which is used to
     display the colors of corners for things like the Bevel, Recess, etc.

     The <grp_no> parameter determines which Button Group subsequent
     RIP_BUTTON commands will be associated with.  Button Groups are used
     to maintain groups of Buttons for things like Radio Buttons and/or
     Checkbox Buttons.  See the section entitled THE BUTTON COMMAND for
     more information on these modes, and what Button Groups can offer.
     This value can range anywhere from 0-Z (i.e., 0-35).  You should not
     mix Checkbox and Radio buttons in the same group. -- unpredictable
     things may happen if you do.

     Some <flags> are mutually exclusive.  For example, you can only have
     one of the "Plain", "Icon", or "Clipboard" flags chosen at once.  To
     better assist you in determining which values can be combined with
     each other, the right-most five columns in the next two tables explain
     if the specific flag can be used under a specific condition.  For
     example, you cannot choose the "Hot Icon" flag if you are dealing with
     a Clipboard Button.  Another example is that you cannot underline the
     hotkey character in the label if it is not a Mouse Button.

     The following table contains the possible flag values for the <flags>
     parameter.  Each of these values may be combined to achieve a
     "composite" group of flags.  See the preceding paragraphs for a more
     detailed explanation of this method.

     VALUE  DESCRIPTION OF FLAGS FIELD #1    ICON CLIP PLAIN MOUSE NO-MOUSE
     ======================================================================
     1      Button is a "Clipboard Button"     N    Y    N     Y      Y
     2      Button is "invertable"             Y    Y    Y     Y      N
     4      Reset screen after button click    Y    Y    Y     Y      N
     8      Display Chisel special effect      Y    Y    Y     Y      Y
     16     Display Recessed special effect    Y    Y    Y     Y      Y
     32     Dropshadow the label (if any)      Y    Y    Y     Y      Y
     64     Auto-stamp image onto Clipboard    Y    Y    Y     Y      Y
     128    Button is an "Icon Button"         Y    N    N     Y      Y
     256    Button is a "Plain Button"         N    N    Y     Y      Y
     512    Display Bevel special effect       Y    Y    Y     Y      Y
     1024   Button is a Mouse Button           Y    Y    Y     Y      N
     2048   Underline hot-key in label         Y    Y    Y     Y      N
     4096   Make Icon Button use Hot Icons     Y    N    N     Y      N
     8192   Adjust vert. centering of label    Y    Y    Y     Y      Y
     16384  Button belongs to a Radio Group    Y    Y    Y     Y      N
     32768  Display Sunken special effect      Y    Y    Y     Y      Y




     The following table describes the possible flag settings for the
     <flags2> parameter:

     VALUE  DESCRIPTION OF FLAGS FIELD #2    ICON CLIP PLAIN MOUSE NO-MOUSE
     ======================================================================
     1      Button is in a Checkbox Group      Y    Y    Y     Y      N
     2      Hilight Hotkey character           Y    Y    Y     Y      N
     4      Explode (Zoom Out when clicked)    Y    Y    Y     Y      N
     8      Left Justify Label (top/cent/bot)  Y    Y    Y     Y      Y
     16     Right Justify Label (" / "  / ")   Y    Y    Y     Y      Y




     ---------------------------------------------------------------------
     Define a Mouse Button
     ---------------------------------------------------------------------
               Symbol: RIP_BUTTON
                Level: 1
              Command: U
            Arguments: x0:2 y0:2 x1:2 y1:2 hotkey:2 flags:1 res:1 ...text
               Format: !|1U <x0> <y0> <x1> <y1> <hotkey> <flags> <res> <text>
              Example: !|1U010100003200iconfile.icn<>Label<>Host Cmd^m
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: YES

     This command physically creates a new Button using the previously
     described RIP_BUTTON_STYLE command.  You may have at most 128
     different Mouse Buttons (you may have any number of non-Mouse
     Buttons).

     The <x0> and <y0> parameters for this command designate the upper-left
     corner of the Button.  This (X,Y) location may not be the actual
     "absolute" corner position of the Button, as it may be adjusted via
     the Special Effects functions that are part of the RIP_BUTTON_STYLE
     command (see above).

     The <x1> and <y1> parameters are only used for Plain Buttons when you
     have not specified a specific Height and Width in the
     RIP_BUTTON_STYLE command.  These parameters are used in Dynamically
     Sized Buttons.  If the Height and Width in the RIP_BUTTON_STYLE are
     non-zero, then these two parameters are set to zero.

     The (x0,y0) and (x1,y1) will be modified by the following values for
     the different special effects:

     EFFECT TYPE    X0 ADJ         Y0 ADJ         X1 ADJ         Y1 ADJ
     =======================================================================
     Bevel          -bevel size    -bevel size    +bevel size    +bevel size
     Recess         -2             -2             +2             +2
     Sunken         0              0              0              0
     Chisel         0              0              0              0


     The <hotkey> parameter is only used with Mouse Buttons.  It is the
     ASCII code for the keystroke that will activate this Button.  It is
     represented as a two-digit MegaNum.  If this character exists in the
     text label, and the Underline flag is enabled in the
     RIP_BUTTON_STYLE, then the character will be underlined in the label.

     The <flags> parameter provides several different functions for each
     button.  The possible "combinatorial" flags for this parameter are
     listed in the following table.  Note that these values may be
     combined together (by adding their values) to arrive at the final
     flag parameter's value.

     Value    Description
     ====================================================================
       1      Draw button as already selected
       2      Button is "default" when <ENTER> is tapped

     Using a flag of 1 means that the Button is already "selected".  By
     selected, we mean that it is already clicked and should be initially
     drawn as clicked.  This is typically used for Radio Buttons and/or
     Check Boxes.  This only affects the image.  The Host Command WILL
     NOT be automatically sent to the host when a selected Button is
     drawn.  If this parameter is set to 0, then the Button will be
     drawn in normal, unselected mode.

     The <text> parameter for this command is somewhat different than those
     found in previously described RIPscrip commands.  All other RIPscrip
     commands only have one text parameter.  This command requires
     anywhere from 0-3 text parameters.  The way RIPscrip accomplishes this
     is by separating each block in the <text> parameter with the
     delimiter "<>".  This text parameter delimiter is not needed before
     the first text block, but is necessary between the 1st and 2nd
     blocks, and the 2nd and 3rd blocks.  Here is an example of a typical
     text parameter for this command:

                 ICONFILE.ICN<>TEXT LABEL<>HOST COMMAND

     The actual syntax of this text parameter is as follows:

              [icon-file][[<>text-label][<>host-command]]

     The block described as ICONFILE.ICN is actually the Icon Filename that
     will be used for the Button if it is an Icon Button.  If it is not an
     Icon Button, then this block will read "<>" all by itself (a "null"
     block).

     The .ICN file extension does not need to be included as part of the
     filename.  If omitted, it will automatically be appended to the
     filename.  If an extension is provided, it will be used verbatim.

     The "TEXT LABEL" block is actually the text that will be used to
     descriptively label the Button.  You may also specify a "null" block
     for no label (i.e., "<>").

     The final block of the <text> parameter is the Host Command.  This
     block contains any text that should be sent to the Host after this
     Button is clicked.  This may contain any Control Characters, Pick-List
     definitions, Text Variables or Template Definitions.  This block
     might be "segmented" into multiple Host Command segments.  See the
     section entitled HOST COMMANDS in this Manual for additional
     information on these Host Command features.

     Not all of the blocks in the <text> parameter need to be specified.
     Here are examples of the valid combinations of text blocks:

     PARAMETER EXAMPLE        DESCRIPTION OF THE TEXT PARAMETER
     ===================================================================
     icon<>label<>host_cmd    Specify all three blocks
     <>label<>host_cmd        2 blocks specified; no icon
     icon<>label<>            2 blocks specified; no host cmd
     icon<>label              2 blocks specified; no host cmd
     <><>host_cmd             1 block specified; no icon or label
     <>label<>                1 block specified; no icon or host cmd
     <>label                  1 bloc specified; no icon or host cmd
     icon<><>                 1 block specified; no label or host cmd
     icon<>                   1 block specified; no label or host cmd
     icon                     1 block specified; no label or host cmd
     <><><>                   A blank text parameter; all blocks omitted
     <><>                     A blank text parameter; all blocks omitted
     <>                       A blank text parameter; all blocks omitted


     NOTE:  The <res> parameter is reserved for future use by TeleGrafix
            Communications, Inc..  It should be set to 0 for compatibility
            with future releases.




     ---------------------------------------------------------------------
     Define a Text Variable
     ---------------------------------------------------------------------
               Symbol: RIP_DEFINE
                Level: 1
              Command: D
            Arguments: flags:3 res:2 ...text
               Format: !|1D <flags> <res> <text>
              Example: !|1D00700text_var,60:?question?default data
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command is used to create a text variable on the Client system
     (i.e., the Terminal system).  A text variable is more fully covered
     in the section entitled HOST COMMANDS.  Simply put, a text variable is
     a piece of information assigned to a 1-12 character identifier that
     can either be saved to a local database file (static variables), or
     to memory (dynamic variables).  Variable Identifiers can be 1-12
     characters in length.  You may use any alphanumeric character and
     underscores (_) in the identifier.  An underscore cannot be the first
     character, nor can the first character of an identifier be a number.

     The <flags> parameter of this command combines three separate values
     into one MegaNum flag that determines how the variable definition
     will operate.  Here are the possible flag values:

                  VALUE     DESCRIPTION OF FLAG
                  =========================================
                  001       Save Variable to database
                  002       Cannot specify a blank response
                  004       Non-interactive query


     When a variable is flagged as "Save to Database", it becomes a part of
     the Client system's actual configuration.  The value is saved
     indefinitely until either changed, or manually erased.  You may choose
     not to allow the user to enter a blank response.  This basically
     requires them to enter some piece of information for the variable.

     The last flag determines whether the definition is interactive or not.
     An interactive definition will attempt to define the variable.  If it
     does exist, it pops the value up on the screen asking the user to
     confirm if the value is correct.  If it does not exist, a similar
     pop-up box will appear asking the user to enter some data for the
     given variable.

     In a non-interactive situation, the Client system will check to see if
     the variable exists.  If it does, then nothing happens (unless a
     default response is specified in this command, whereby the Client's
     variable is updated with the new information).  If the value is not
     defined, then this definition becomes interactive by default, since
     the user actually has to enter something anyway.

     The <text> parameter for this command is also segmented in nature,
     much like the RIP_BUTTON command is.  An example of a segmented
     <text> parameter for the RIP_DEFINE command might be as follows:


               FULL_NAME,30:?What is your full name?John Doe


     The actual syntax of the Variable Define text parameter is as follows:


       variable-identifier[,field-width]:[?question-text?][default-value]


     There are several different segments in this parameter as you can see.
     The first section is the variable- identifier.  Immediately after it
     is an optional field-width.  If the field width is omitted, it will
     default to a value of  60.  You should limit the values of this width
     from 1-60.

     Immediately following the identifier field-width parameter is a colon
     (:).  The colon indicates that the variable identifier field is
     completed and that the remainder of the text parameter is to contain
     the question and/or the default response (if any).  If no question or
     default response is provided, the text parameter would read
     "TEXT_VAR,width:" with no additional data.

     The question-text is specified by a question mark (?) followed by the
     actual text of the question, followed by a trailing question mark.
     The basic format of the question segment is as follows:


                             ?this is a question?


     The remainder of the text parameter consists of a default-value for
     the variable's contents.  It may be omitted if you wish, to make it
     so that the user must enter his/her own value instead of some "canned
     response".


     NOTE:  The <res> parameter is reserved for future use by TeleGrafix
            Communications, Inc..  It should be set to 00 for compatibility
            with future releases.





     ---------------------------------------------------------------------
     Query the contents of a Text Variable
     ---------------------------------------------------------------------
               Symbol: RIP_QUERY
                Level: 1
              Command: <escape>
            Arguments: mode:1 res:3 ...text
               Format: !|1<escape> <mode> <res> <text>
              Example: !|1<escape>0000this is a query $COMMAND$^m
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     The Query Text Variable RIPscrip command instructs the Client system
     to immediately respond with some piece of information, whether
     statically stored (i.e., in a database), stored internally in RAM
     (dynamic information), or pre-defined Text Variables.

     This command is unique in RIPscrip in the fact that the command
     character that is used is NOT a printable character.  We use the
     Escape character (ascii 27) to introduce this command as a measure
     of Security.  Since the Query command can query the terminal for
     some critical (potentially private) information, you would not
     want a End-User to be able to Query another User's terminal for
     something like his Address Information, or something that he
     wouldn't want to otherwise divulge to unauthorized people.  Since
     most BBS'es do not allow the User to enter an Escape character,
     this character is ideal for this purpose.  Using an Escape, allows
     only the Host under most circumstances to be in control of any
     Queries.

     This command is very flexible in that you can specify Control
     Characters, Pick-List definitions, Text Variable insertion, and even
     Host Command Template definitions.  See the section of this Manual
     entitled HOST COMMANDS for a more detailed explanation of Host
     Commands and these specific features.

     Whether the information is transmitted instantly or not is dependant
     on the <mode> parameter.  The <mode> parameter determines when data
     queries are processed.  The possible settings for the <mode> parameter
     are as follows:

          MODE      DESCRIPTION
          ========================================================
            0       Process the query command NOW (upon receipt)
            1       Process when mouse clicked in Graphics Window
            2       Process when mouse clicked in Text Window
                    (any text variables that return X or Y mouse
                    coordinates return TEXT coordinates, not
                    graphics coordinates in this mode.  These
                    coordinates are two-digit values instead of
                    the graphical values that are four digits).

     Note that modes 1-2 do not return the results of the Query instantly.
     They query commands are processed when the user clicks the mouse
     either in the text window, or in the graphics window respectively.
     These "queries after mouse clicks" are only acted upon if the user
     is clicking on something other than a Button or a Mouse Field.
     To disable these two special "deferred" query modes, issue the
     same command with the query string of $OFF$.  This will disable
     this mode.  Providing a <text> parameter of anything other than
     $OFF$ will produce a revised query command (active).

     Basically put, a Query command will be immediately acted upon by the
     Terminal program when received.  The Query command's <text> parameter
     can contain any number of Host Command "segments", which can instruct
     the terminal "how to" send data to the host, and more specifically,
     what data to send to the host.

     Some examples of query statements might be any of the following:

        ^m  ......................... Send a carriage return to the BBS
                                      right now
        My name is $FULL_NAME$^m  ... Send the text "My name is
                                      <insert-name-here>" followed by a
                                      carriage return to the BBS.  The
                                      <insert-name-here> will be replaced
                                      with whatever the the variable
                                      $FULL_NAME$ contains.

     See the section entitled HOST COMMANDS for a detailed explanation of
     Host Commands, and what you can do with the Query command.

     NOTE:  The <res> parameter is reserved for future use by TeleGrafix
            Communications, Inc..  It should be set to 000 for
            compatibility with future releases.




     ---------------------------------------------------------------------
     Copy screen region up/down
     ---------------------------------------------------------------------
               Symbol: RIP_COPY_REGION
                Level: 1
              Command: G
            Arguments: x0:2 y0:2 x1:2 y1:2 res:2 dest_line:2
               Format: !|1G <x0> <y0> <x1> <y1> <res> <dest_line>
              Example: !|1G080G140M0005
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command physically "copies" a rectangular region of the
     graphics screen up or down.  The <dest_line> parameter is the Y
     position that is the destination scan line to receive the region.
     The Destination of the copy can overlap the original region, but
     cannot be on the same line.  You cannot move the image area left or
     right at all.  This command is designated for vertical scrolling of
     graphical data either up or down.

     Due to hardware restrictions, the X0 and X1 parameters must be evenly
     divisible by eight (8) (e.g., 0, 8, 16, etc).  If the X0 and X1
     parameters are NOT evenly divisible by eight, then the X0 parameter
     will be reduced to the next most eight-pixel boundary, and the X1
     parameter will be increased to the next eight-pixel boundary.  For
     example, if X0=14, and X1=38, then X0 would be adjusted DOWN to 8,
     and X1 would be adjusted UP to 40.  This is to ensure that the
     desired graphical region is scrolled.

     The original image area is left on the screen (is not cleared).  So
     if you wish to perform some kind of scrolling effect, you will have
     to clear the original area yourself.

     If the destination region would place the image partially off-screen,
     then the entire command is ignored!


     NOTE:  The <res> parameter is reserved for future development by
            TeleGrafix.





     ---------------------------------------------------------------------
     Playback local .RIP scene file
     ---------------------------------------------------------------------
               Symbol: RIP_READ_SCENE
                Level: 1
              Command: R
            Arguments: res:8 filename...
               Format: !|1R <res> <filename>
              Example: !|1R00000000testfile.rip
      Uses Draw Color: YES
      Uses Line Patrn: YES
      Uses Line Thick: YES
      Uses Fill Color: YES
      Uses Fill Patrn: YES
      Uses Write Mode: YES
      Uses Font Sizes: YES

     This command instructs the remote terminal to playback a local .RIP
     file.  The current execution of RIPscrip commands will be temporarily
     suspended and the contents of the designated RIP file will begin
     executing.  Regardless of whether or not the current RIPscrip code
     coming across the modem is in the middle of a line or not, the RIP
     playback file will be assumed to start at the beginning of a line.
     Therefore, if a RIP_READ_SCENE command is located in a .RIP file,
     it must be the very last command on the line, followed by a carriage
     return instead of a command delimiter (|).  This ensures that the
     loaded .RIP file will begin executing properly with the correct
     delimiters found in the correct places.

     The RIP playback file can alter colors, fonts, or whatever.  Once
     the playback of the file is complete, the remaining RIPscrip code
     that was temporarily suspended will be resume execution.  Any changes
     that appeared in the loaded playback file will remain in effect when
     the resumed code is processed.  In other words, if you change a color
     or a font in the playback file and leave them changed, they will
     remain in effect during the resumed execution.

        NOTE:  The <res> parameter is reserved for future development
               by TeleGrafix.  It should be set to "00000000" for
               compatibility with future releases.




     ---------------------------------------------------------------------
     Query existing information on a particular file
     ---------------------------------------------------------------------
               Symbol: RIP_FILE_QUERY
                Level: 1
              Command: F
            Arguments: mode:2 res:4 filename...
               Format: !|1F <mode> <res> <filename>
              Example: !|1F010000testfile.icn
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command queries the existance of a particular file, regardless
     of file type.  It is intended for use by Host systems to determine
     if a particular Icon or RIP file exists on the remote terminal's
     hard disk.

     There are a variety of ways you can query for filenames.  The <mode>
     parameter determines the method that this command will respond to
     the Host.  Note that this command instructs the terminal to send
     a response to the Host immediately upon execution of this command.

     The following table is a listing of the possible values for <mode>:

          VALUE     DESCRIPTION
          ==============================================================
           00       Simply query the existance of the file.  If it
                    exists, a "1" is returned.  Otherwise a "0" is
                    returned to the Host (without a carriage return).
           01       Same as 0 above, except a carriage return is
                    added after the response.
           02       Queries the existance of a file.  If it does not
                    exist, a "0" is returned to the Host followed by a
                    carriage return.  If it does exist, the returned
                    text is a "1." followed by the file size (in
                    decimal).  The return sequence is terminated by a
                    carriage return.  An example of the returned text
                    could be "1.20345".
           03       Queries extended return information.  If the file
                    does not exist, a "0" is returned follwed by a
                    carriage return.  If it does exist, the text
                    returned to the Host is in the format:
                    1.size.date.time <cr>.  An example of a return
                    statement could be "1.20345.01/02/93.03:04:30 <cr>"
           04       Queries extended return information.  If the file
                    does not exist, a "0" is returned follwed by a
                    carriage return.  If it does exist, the text
                    returned to the Host is in the format:
                    1.file.size.date.time <cr>.  An example of a return
                    statement could be

                        "1.MYFILE.RIP.20345.01/02/93.03:04:30 <cr>".

                    Note the file extension adds another period into the
                    text.




     ---------------------------------------------------------------------
     Enter "block transfer" mode with Host
     ---------------------------------------------------------------------
               Symbol: RIP_ENTER_BLOCK_MODE
                Level: 10 (system command)
              Command: <escape>
            Arguments: proto:2 file_type:2 res:4 [filename:2] <>
               Format: !|0<escape> <proto> <file_type> <res> [filename] <>
              Example: !|0<escape>00000001iconfile.icn<>
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

      This command is used to auto-initiate any desired File Transfer
      Protocol.  The <filename> parameter is optional, and if omitted
      must be replaced with a "<>" parameter (end of string).

      The <proto> parameter is the file transfer protocol specifier.
      Possible values, and the protocols they refer to are:


          VALUE     PROTOCOL            FILENAME REQUIRED?
          ================================================
            0       Xmodem (checksum)          Yes
            1       Xmodem (CRC)               Yes
            2       Xmodem-1K                  Yes
            3       Xmodem-1K (G)              Yes
            4       Kermit                     Yes
            5       Ymodem (batch)             No
            6       Ymodem-G                   No
            7       Zmodem (crash recovery)    No

     The <file_type> parameter determines what types of files are to be
     received during the block transfer.  The following values apply
     to the <file_type> parameter:

          VALUE     DESCRIPTION OF BLOCK TRANSFER CONTENTS
          ================================================================
            0       .RIP file sequence (display it)
            1       .RIP file sequence (store them)
            2       .ICN file sequence (store them in proper directories)
            3       .HLP file sequence (store it, and auto-load if needed)
            4       COMPOSITE DYNAMIC file sequence (batch protcols only)
            5       ACTIVE DYNAMIC file sequence (batch protcols only)

     Whether the <filename> is specified or not, this command must have
     a "<>" sequence after the filename (even if omitted).  Here are
     examples of how it would look with and without a filename:


          !|0B0101filename.icn<> ... With filename field (Xmodem-CRC)
          !|0B0604<> ............... w/o  filename field (Zmodem)

     The special <file_type> of 4 & 5 (COMPOSITE DYANAMIC file sequences)
     is somewhat different than the non-batch transfer methods.  This allows
     each file uploaded to be individually processed based on their
     file extensions.  If you use extensions other than .RIP or .ICN, then
     this mode is not available to you as the necessary files will not be
     able to be processed.  Any files that are "downloaded" from the Host
     in DYNAMIC mode are placed into the appropriate sub-directories and
     no further processing is performed.  .RIP files that are received
     are "stored" and are not played back in COMPOSITE DYNAMIC mode.  In
     ACTIVE DYNAMIC mode, they are stored and played back simultaneously.

     NOTE: This command must be terminated with a carriage return.  A
           vertical bar (|) command delimiter cannot be used to separate
           this command from a subsequent one on the same line.  In other
           words, this command must be the last command on a line of text.
           The Protocol must begin on the very next line.





     ---------------------------------------------------------------------
     End of RIPscrip Scene
     ---------------------------------------------------------------------
               Symbol: RIP_NO_MORE
                Level: 0
              Command: #
            Arguments: <none>
               Format: !|#
              Example: !|#
      Uses Draw Color: NO
      Uses Line Patrn: NO
      Uses Line Thick: NO
      Uses Fill Color: NO
      Uses Fill Patrn: NO
      Uses Write Mode: NO
      Uses Font Sizes: NO

     This command indicates that RIPscrip commands are complete.  This
     allows the terminal program to activate Mouse Regions, or respond to
     queued up Mouse Clicks without disturbing the natural flow of the
     script transmission.

     For noise-immunity, the Host should transmit three or more
     RIP_NO_MORE command consecutively to make sure the message gets to
     the terminal.  The terminal should also time-out if no data is
     received for a while, and assume RIP_NO_MORE.










     =====================================================================
     ==          HOST COMMANDS - A TUTORIAL & REFERENCE SECTION         ==
     =====================================================================

     With Mouse regions, Buttons and Text Variable Query ability, you can
     control the Terminal/Paint programs and how they react with the BBS
     in many ways.  To accomplish this, there are several features of
     RIPscrip that permit you to do special actions based on different
     circumstances.  In effect, an "action language" of sorts.  The
     following sections go into the available "action language" features
     in more detail.

     Among the various abilities are:

          1. Control-Character specification
          2. Pre-defined Text Variables & User-defined text variables
          3. Pop-up pick-lists
          4. A Host Command "Template" system for added intelligence.
          5. Query text variable contents (pre-defined & user variables)




     =====================================================================
     ==                        CONTROL CHARACTERS                       ==
     =====================================================================

     Not all BBS'es will allow you to use control characters on their
     Service.  Regardless of that, the capability to send any Control
     Character exists for your Host Commands.  The most commonly used
     Control Characters are:

        INDIVIDUAL CONTROL CHARACTERS         SPECIAL KEYSTROKES
        ===========================================================
        ^G ... Beep                           ^[[A ... Up Arrow
        ^L ... Clear Screen (Top of Form)     ^[[B ... Down Arrow
        ^M ... Carriage Return                ^[[C ... Right Arrow
        ^C ... Break (sometimes)              ^[[D ... Left Arrow
        ^H ... Backspace                      ^[[H ... Home Key
        ^[ ... Escape character               ^[[K ... End Key
        ^S ... Pause data transmission        ^[[L ... Control Home
        ^Q ... Resume data transmission

     Some hosts use the ^ (caret) for their own purposes.  In these
     cases, you can use the ` (backquote) character instead of the
     caret.  Some systems allow you to specify the caret symbol as
     two carets (^^).  Consult your Host Software documentation to
     determine the best method for your needs.




     =====================================================================
     ==                          TEXT VARIABLES                         ==
     =====================================================================

     A special feature of RIPaint allows it to understand what a Text
     Variable is.  A text variable is a piece of text that both RIPaint
     and RIPterm know something about.  For example, the Text Variable
     $DATE$ is known to represent the current Date on your PC.  The BBS
     may ask your PC what the values of one or more of these variables
     are, and if your Terminal knows those particular Variables, it will
     tell the BBS.

     There are two types of Text Variables.  There are built-in Text
     Variables that RIP products will ALWAYS know about.  Then there are
     also User Text Variables that can contain a variety of information
     depending on what the User entered at the time the Variable was
     created.  For example, the BBS might ask you what the contents of
     the $FULL_NAME$ variable is, and if RIPterm doesn't know, it could
     pop-up a field on the screen and ask you about it.  From then on,
     RIPterm will remember that piece of information for the next time it
     is needed by a BBS.

     You may use either the pre-defined Text Variables, or the User Text
     Variables at any place that allows Text Variables.


     The following is a Listing of the Pre-Defined Text Variables:
     =============================================================


     $DATE$ ... Date in short format (e.g., 12/19/93)
     ------------------------------------------------
     This Text Variable will be transformed into the current Date.
     It will be displayed in the format MM/DD/YY.

          Example:  $DATE$ = 12/19/93


     $MONTH$ ... Month Name
     ----------------------
     This Text Variable will be transformed into the name of the
     Current Month.  It will be not abbreviated (e.g., "November"
     instead of "Nov")

          Example:  $MONTH$ = December


     $MONTHNUM$ ... Month (in format 1-12)
     -------------------------------------
     This Text Variable is transformed into a Number representing
     the Current Month.  January=01 and December=12.  Therefore,
     the possible values for $MONTHNUM$ can range from 01-12.

          Example:  $MONTHNUM$ = 12


     $DAY$ ... Day in numeric form (e.g., 31)
     ----------------------------------------
     This Text Variable is transformed into a Number representing
     the Current Day of the month.  Possible values for this
     Variable are from 01-31.

          Example:  $DAY$ = 05


     $DOY$ ... Day of year (001-366)
     -------------------------------
     This Text Variable will be transformed into a Number representing
     the Day of the current Year.  Since a year contains 365 days (unless
     it is a Leap-Year where it contains 366), then the possible values
     that $DOY$ can be are 001-366.

          Example: $DOY$ = 214


     $YEAR$ ... 2 digit year (without century) (00-99)
     -------------------------------------------------
     This Text Variable will be transformed into a two-digit number
     representing the Current Year.

          Example: $YEAR$ = 93


     $FYEAR$ ... 4 digit year (with century) (0000-9999)
     ---------------------------------------------------
     This Text Variable will be transformed into a four-digit number
     that represents the Current Year.

          Example:  $FYEAR$ = 1993


     $TIME$ ... Time in standard format (e.g., 12:03:14)
     ---------------------------------------------------
     This Text Variable will be transformed into the Current Time.
     The time will be in military format (hours from 00-23).

          Example:  $TIME$ = 18:09:33


     $HOUR$ .... Hour (format HH) - normal style
     -------------------------------------------
     This Text Variable will be transformed into a two-digit number
     representing the Current Hour.  This variable may be anywhere
     from 01-12.  This does not use Military format.

          Example:  $HOUR$ = 11


     $MHOUR$ ... Hour (format HH) - Military style
     ---------------------------------------------
     This Text Variable will be transformed into a two-digit number
     representing the Current Hour in military format.  This variable
     may range anywhere from 00-23.

          Example: $MHOUR$ = 17


     $MIN$ ... Minutes (00-59)
     -------------------------
     This Text Variable will be transformed into a two-digit number
     representing the Current Minutes in the Hour.  Possible values
     for this Variable are 00-59.

          Example:  $MIN$ = 45


     $SEC$ ... Seconds (00-59)
     -------------------------
     This Text Variable will be transformed into a two-digit number
     representing the Current Seconds of the Minute.  Possible values
     for this Variable are 00-59.

          Example: $SEC$ = 59


     $AMPM$ ... Returns either AM or PM depending on time
     ----------------------------------------------------
     This Text Variable will be transformed into a two-character
     value of either "AM" or "PM" depending on what time it is.

          Example: $AMPM$ = PM


     $DATETIME$ ... Date & Time (e.g., Sat Dec 19 14:38:50 1992)
     -----------------------------------------------------------
     This Text Variable will be transformed into a combination Date
     and Time.  The format is somewhat different than standard
     Time/date notation.  The format used is:

       DAY-OF-WEEK   MONTH   DAY-OF-MONTH  HH:MM:SS  YEAR

          Example:  $DATETIME$ = Sat Dec 19 14:38:50 1992

     NOTE: This is the standard UNIX date/time notation.


     $TIMEZONE$ ... Time Zone or "NONE" if unknown (e.g., Pacific)
     -------------------------------------------------------------
     This Text Variable will be transformed into a a word/phrase that
     describes the Current Time-Zone you are in.  This may be returned
     as anything like "PST" for Pacific Standard Time, "EST" for Eastern
     Standard Time, etc.  If the Time-Zone is not set on your PC, this
     Variable will respond with "NONE".

          Example: $TIMEZONE$ = PST


     $DOW$ ... Day of week fully spelled out (e.g., Friday)
     ------------------------------------------------------
     This Text Variable will be transformed into the Current Day
     of the Week.  The name will be fully spelled out.  This
     Variable can be any of the values: Sunday, Monday, Tuesday,
     Wednesday, Thursday, Friday and Saturday.

          Example:  $DOW$ = Saturday


     $ADOW$ ... Abbreviated Day of Week (e.g., Mon, Tue, etc)
     --------------------------------------------------------
     This Text Variable will be transformed into the Current Day
     of the week, in abbreviated form.  This variable may be any
     of the following values: Sun, Mon, Tue, Wed, Thu, Fri and Sat.

          Example:  $ADOW$ = Mon


     $WDAY$ ... Weekday where 0 is Sunday (0-6)
     ------------------------------------------
     This Text Variable will be transformed into a one-digit number
     representing the Number of the Day of the Week.  Possible values
     for this Variable are 0-6, where 0=Sunday (the first day in the
     week).

          Example: $WDAY$ = 2


     $WOY$ ... Week of current year 00-53; Sunday=1st Day of Week
     ------------------------------------------------------------
     This Text Variable will be transformed into a number from 00-53,
     representing the Week Number in the current year.  Even though
     there are 52 weeks in a year, a week might not begin exactly on
     the first day of the year, so a maximum value for this variable
     can be 53 under these circumstances.  For this Variable, SUNDAY
     is considered to be the first day of the week.

          Example:  $WOY$ = 32


     $WOYM$ ... Week of current year 00-53; Monday=1st Day of Week
     -------------------------------------------------------------
     This Text Variable will be transformed into a number from 00-53,
     representing the Week Number in the current year.  Even though
     there are 52 weeks in a year, a week might not begin exactly on
     the first day of the year, so a maximum value for this variable
     can be 53 under these circumstances.  For this Variable, MONDAY
     is considered to be the first day of the week.

          Example:  $WOYM$ = 32


     $RIPVER$ ... RIPterm version (e.g., "RIPSCRIP015100")
     -----------------------------------------------------
     This Text Variable will be transformed into a key-phrase which
     will identify a RIPterm software package.  It is designed to
     be used by a Host BBS to detect what version of RIPscrip
     graphics your Terminal can support.  When this Text Variable
     is used, it will respond back with "RIPSCRIP" followed by
     the full Version Number (e.g., 01.51.00), without the periods.

          Example: $RIPVER$ = RIPSCRIP015100


     $STATBAR$ ... If Status Bar is on, returns YES, otherwise NO
     ------------------------------------------------------------
     This Text Variable will be transformed into a "YES" if the Status
     Bar is currently On on the Terminal.  If the Status Bar is not
     visible, then this Variable will be "NO".

          Example:  $STATBAR$ = YES


     $X$ ... X Mouse location   (format: XXXX)
     -----------------------------------------
     This Text Variable is for reporting the current X location of
     the Mouse to the BBS.  This could be used interactively by the
     BBS (or a game on the BBS) to deterimine the location of the
     mouse cursor.  Only the X value of the Mouse (X,Y) location is
     returned to the BBS.  The value will be 0000-9999 depending on
     what the current position is.

          Example:  $X$ = 0523


     $Y$ ... Y Mouse location   (format: YYYY)
     -----------------------------------------
     This Text Variable is for reporting the current Y location of
     the Mouse to the BBS.  This could be used interactively by the
     BBS (or a game on the BBS) to deterimine the location of the
     mouse cursor.  Only the Y value of the Mouse (X,Y) location is
     returned to the BBS.  The value will be 0000-9999 depending on
     what the current position is.

          Example:  $Y$ = 0244


     $XY$ ... X/Y Mouse Location (format: XXXX:YYYY)
     -----------------------------------------------
     This Text Variable will be transformed into a combination of
     both the X and Y locations of the Mouse Cursor.  A colon (:) is
     used to separate the two values.  Either the X or Y values may
     range from 0000-9999 depending on the current location.  The
     format that this value takes on is:  XXXX:YYYY

          Example:  $XY$ = 0297:0321


     $XYM$ ... X, Y & button status (format: XXXX:YYYY:LMR)
     ------------------------------------------------------
     This Text Variable will be transformed into a combination of
     the X and Y Mouse Cursor location, and a status of which
     Mouse Buttons are pressed (if any).  The format of the returned
     text is XXXX:YYYY:LMR where XXXX is the X cursor location in the
     range 0000-9999.  YYYY is the Y cursor location in the range
     0000-9999.  Finally, LMR stands for Left/Middle/Right.  If any
     of these buttons are depressed (clicked), then the corresponding
     position will contain a 1.  If a button is NOT depressed, then it
     will contain a 0.

          Example:  $XYM$ = 0123:0297:110

     This means that the (X,Y) location of the cursor is (0123,0297),
     and that the Left and Middle buttons are depressed, but that the
     Right Mouse Button is not depressed.


     $M$ ... Mouse Button Status: LMR (e.g., 101)
     --------------------------------------------
     This Text Variable will be transformed into a 3-character code
     representing what the Status of each Mouse Button is.  This
     variable can work with either 2-button Mice, or 3-button Mice.
     In either event, the format of the code is LMR where L=Left,
     M=Middle (if any), and R=Right.  If any of these buttons are
     depressed (i.e., clicked), then the code for that button would be
     a "1".  If the button is not depressed, it is a "0".  So, a value
     of "100" would mean that the Left Mouse Button is depressed, but
     none of the others are.

          Example:  $M$ = 001


     $MSTAT$ ... Mouse Status (format: YES/NO)
     -----------------------------------------
     This Text Variable will be transformed into a "YES" if there is
     a Mouse installed on the RIPterm computer.  If no Mouse is
     installed, this variable will contain "NO".

          Example:  $MSTAT$ = YES


     $SBARON$ ... Turn ON the Status Line
     ------------------------------------
     This Text Variable is somewhat different than the other Text
     Variables described above.  Rather than send something back
     to the Host, it performs a specific operation - it turns ON
     the Status Line.  In this respect, it is considered an ACTIVE
     TEXT VARIABLE.  It evaluates to a null string (nothing).  Its
     sole purpose in life is to enable the Status Line.

          Example:  $SBARON$ = <nil>


     $SBAROFF$ ... Turn OFF the Status Line
     --------------------------------------
     This Text Variable is somewhat different than the other Text
     Variables described above.  Rather than send something back
     to the Host, it performs a specific operation - it turns OFF
     the Status Line.  In this respect, it is considered an ACTIVE
     TEXT VARIABLE.  It evaluates to a null string (nothing).  Its
     sole purpose in life is to disable the Status Line.

          Example:  $SBAROFF$ = <nil>


     $ETW$ ... Erase Text Window
     ---------------------------
     This Text Variable is somewhat different than the other Text
     Variables described above.  Rather than send something back
     to the Host, it performs a specific operation - it Erases the
     current Text Window (much like a Clear Screen code does).  This
     command is particularly useful in Host Commands when you click
     on a Mouse area, and after it is finished clicking, it could
     erase the text window THEN transmit the remainder of the host
     command (if any) to the BBS.

          Example:  $ETW$ = <nil>


     $EGW$ ... Erase Graphics Window
     -------------------------------
     This Text Variable is somewhat different than the other Text
     Variables described above.  Rather than send something back
     to the Host, it performs a specific operation - it Erases the
     current Graphics Window (much like a Reset Windows command does).
     This command is particularly useful in Host Commands when you
     click on a Mouse area, and after it is finished clicking, it
     could erase the graphics window THEN transmit the remainder of
     the host command (if any) to the BBS.

          Example:  $EGW$ = <nil>


     $MKILL$ ... Kill all Mouse Fields currently defined
     ---------------------------------------------------
     This Text Variable is also an "Active Text Variable" in the
     sense that it doesn't transmit anything per se to the Host.
     What it does do, is upon execution it deletes all currently
     defined Mouse Fields exactly like the RIP_KILL_MOUSE_FIELDS
     does.  The net benefit of this is that when the user clicks
     on a Mouse Button, the Mouse Fields are removed, but the
     graphics remain on the screen so that the fields could be
     subsequently re-defined quickly and easily without having to
     re-transmit an identical menu over again.

          Example:  $MKILL$ = <nil>


     $BEEP$ ... Beeps the terminal (like a CTRL-G does)
     --------------------------------------------------
     This command is an Active Text Variable.  It's sole purpose
     in life is to issue a Beep to the Terminal, thus producing
     a CTRL-G sound.

          Example:  $BEEP$ = <nil>


     $BLIP$ ... Makes a short "blipping" sound (like a Barrier)
     ----------------------------------------------------------
     This Active Text Variable is much like the BEEP variable,
     except that the sound produced is different.  It produces
     a sound more akin to a "barrier" sound; something that
     sounds like you're running into a wall or something to that
     effect.

          Example:  $BLIP$ = <nil>


     $MUSIC$ ... Makes a musical (cheerful) sound
     --------------------------------------------
     This Active Text Variable also produces an Audio result.  The
     sound that is generated is a cheerful sound, representing
     some kind of success.  The sound is exactly the same as the
     Sound you would hear when you receive a successful download,
     or when you achieve a connection when dialing the modem in
     RIPterm.


     $DTW$ ... Disable Text Window
     -----------------------------
     This Text Variable is somewhat different than the other Text
     Variables described above.  Rather than send something back
     to the Host, it performs a specific operation - it Disables the
     current Text Window (preventing any received text from showing
     up on screen).  This command is particularly useful in Host
     Commands when you click on a Mouse area, and after it is
     finished clicking, it would halt any further text output to
     the text window.

          Example:  $DTW$ = <nil>


     $PCB$ ... Paste Clip Board at last location
     -------------------------------------------
     This command will physically paste the contents of the clipboard
     at the last location that the clipboard was "clipped" from.
     This even works with Icons that are loaded.  The last location
     taken in this situation, is the location the Icon was stamped
     when it was originally loaded.  This text variable is very
     useful in situations where you want to "pop-up" a dialog box
     on the screen (saving the previous area behind the dialog onto
     the clipboard), and when the user clicks on the "OK" button,
     restoring the screen contents (by adding a $PCB$ in the host
     command string).

          Example:  $PCB$ = <nil>


     $SMF$ ... Save Mouse Fields
     ---------------------------
     This text variable will physically save all currently defined
     Mouse Fields and Mouse Buttons to a temporary file for later
     retrieval.  This is designed especially for the graphical
     designer who wishes to pop-up a dialog box on the screen with
     one or more mouse fields, and when finished, to restore the
     screen and original mouse fields (if any) so that the user is
     not left "floating".  This command is intended to be used with
     the Restore Mouse Fields text variable $RMF$.

          Example:  $SMF$ = <nil>


     $RMF$ ... Restore Mouse Fields
     ------------------------------
     This text variable physically restores any previously saved
     Mouse Fields saved with the $SMF$ text variable.  You may
     have only one set of mouse fields saved at any one time.  If
     there were no mouse fields saved, or if the number of mouse
     fields that were saved was 0, then no mouse fields will be
     active.  Any fields that were defined at the time of this
     command's execution will be erased.

     NOTE: You may restore Mouse Fields more than once if you wish.
           In other words, if you perform a "Save Mouse Fields"
           command, you may execute Restore Mouse Fields one or
           more times after that point.

          Example:  $RMF$ = <nil>


      $COFF$ ... Disable the text cursor
      ----------------------------------
      This command will physically shut off the ASCII text cursor that
      is normally seen in the text window.  This is automatically reset
      whenever a $CON$ command (Cursor ON) or a Reset Windows command
      is received.

          Example:  $COFF$ = <nil>


      $CON$ ... Re-displays the text cursor
      -------------------------------------
      This command will physically turn ON the ASCII text cursor.  This
      is the exact opposite of the $COFF$ command which disables the
      text cursor.

          Example:  $CON$ = <nil>


      $STW$ ... Save text window information
      --------------------------------------
      This command will physically store all of the text window
      settings.  The window's X/Y dimensions are preserved, as is the
      current cursor location, ANSI attributes, cursor ON/OFF status
      and the vertical scrolling margins.  Even the current System Font
      will be saved (if necessary).

          Example:  $STW$ = <nil>


      $RTW$ ... Restore text window information
      -----------------------------------------
      This command will restore the text window to whatever settings
      were active when the $STW$ (save text window) command was issued.
      The cursor, ANSI attributes and any other piece of text window
      information will be restored (including the System Font setting).

      NOTE: The textual contents of the window will not be restored.

          Example:  $RTW$ = <nil>


      $SCB$ ... Save Clip Board
      -------------------------
      This command will save the Clipboard to disk for later retrieval
      by a subsequent Query or Host Command.  If the clipboard does
      not exist, then the temporary file is deleted automatically to
      indicate to the Restore Clip Board that there shouldn't be a
      clipboard active.

          Example:  $SCB$ = <nil>


      $RCB$ ... Restore Clip Board
      ----------------------------
      This command restores the clipboard from the temporary disk file
      called SCRAPBUF.SAV.  This file is created by $SCB$ (save clip
      board).  Not only is the actual clipboard contents saved, but
      so is the last clipboard location, so that the Paste Clip Board
      command ($PCB$) will restore the clipboard's location as well.

          Example:  $RCB$ = <nil>


      $VT102ON$ ... Turn VT-102 keyboard mode ON
      ------------------------------------------
      This command enables the VT-102 keystrokes ability.  This makes
      the following keystrokes send something to the Host:

                             F1 ...  ESC [ M
                             F2 ...  ESC [ N
                             F3 ...  ESC [ O
                             F4 ...  ESC [ P
                             F5 ...  ESC [ Q
                             F6 ...  ESC [ R
                             F7 ...  ESC [ S
                             F8 ...  ESC [ T
                             F9 ...  ESC [ U
                            F10 ...  ESC [ V
                           PGUP ...  ESC [ I
                           PGDN ...  ESC [ G
                           HOME ...  ESC [ H
                            END ...  ESC [ F
                         INSERT ...  ESC [ L
                      CURSOR UP ...  ESC [ A
                      CURSOR DN ...  ESC [ B
                    CURSOR LEFT ...  ESC [ C
                   CURSOR RIGHT ...  ESC [ D

      The purpose of having this as a text variable is that the Host
      can instruct the terminal to enter this mode automatically, thus
      making it simpler on the user.

          Example:  $VT102ON$ = <nil>


      $VT102OFF$ ... Turn VT-102 keyboard mode OFF
      --------------------------------------------
      This variable disables the VT-102 keystrokes mode, returning your
      keyboard to the standard keyboard operation.

          Example:  $VT102OFF$ = <nil>


      $DWAYON$ ... Turn Doorway Mode ON
      ---------------------------------
      This variable enables Doorway Mode.  This is intended to be used
      by a Host system that wishes to take advantage of the Doorway
      mode available in Marshall Dudley's Doorway (tm) software
      package.

          Example:  $DWAYON$ = <nil>


      $DWAYOFF$ ... Turn Doorway Mode OFF
      -----------------------------------
      This variable disabled the Doorway keyboard mode.  This will
      return the keyboard to normal operation.

          Example:  $DWAYOFF$ = <nil>


      $SAVE$ ... Save graphics screen
      -------------------------------
      The SAVE variable will completely save the contents of the entire
      graphics screen to a disk file called RIPTERM.SAV.  No Mouse
      Fields, Text Window locations or Clipboard data are saved - just
      the graphics screen.  The entire 640x350 region is saved to disk.

      If you wish to save the entire state of the RIPterm system, use
      the following text variables all at the same time (spaces are
      added for clarity):

              $SAVE$ $STW$ $SCB$ $SMF$
                 \     \     \     \
                  \     \     \     --- Save Mouse Fields
                   \     \     \
                    \     \     ------- Save ClipBoard
                     \     \
                      \     ----------- Save Text Window
                       \
                        --------------- Save Graphics Screen


      $RESTORE$ ... Restore graphics screen
      -------------------------------------
      The RESTORE command will read the saved file RIPTERM.SAV in from
      disk and restore the graphics as they were originally saved with
      the $SAVE$ command.  Only the graphics screen is restored, not
      the Clipboard, Mouse Fields or Text Window settings.  To restore
      the entire context of the graphics environment, issue the
      following text variables:

              $RESTORE$ $STW$ $SCB$ $SMF$
                 \        \     \     \
                  \        \     \     --- Restore Mouse Fields
                   \        \     \
                    \        \     ------- Restore ClipBoard
                     \        \
                      \        ----------- Restore Text Window
                       \
                        ------------------ Restore Graphics Screen


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

    $SAVE0$-$SAVE9$ & $RESTORE0$-$RESTORE9$ ... Save/Restore screens

    These ten text variables are identical in nature with $SAVE$
    described above with sole exception to the fact that the temp
    files (RIPTERM0.SAV - RIPTERM9.SAV) are immediately deleted
    when restored.  The $SAVE$ and $RESTORE$ commands do not do this.
    With this, you can keep restoring screens if you use $SAVE$.
    These ten variables are provided so that you can have more than
    one screen saved simultaneously.




     =====================================================================
     ==                 LOCAL RIPscrip FILE PLAYBACK                    ==
     =====================================================================


      You can re-play a .RIP file that you have locally on your hard disk
      from anyplace that allows text variables.  The format of the variable
      is somewhat different than user variables, or pre-defined text
      variables.  After the initial dollar sign ($), enter the greater-than
      symbol (>) followed by the filename (with or without the .RIP
      extension), then ending in another dollar sign ($).  Several examples
      of this are as follows:

               $>MYFILE.RIP$
               $>FILE1$
               $>FILE1.RIP$$>FILE2.RIP$$>FILE3$
               $>ANSIFILE.ANS$

      Note in the last example, a file extension other than .RIP was used.
      You are not limited to playing back local .RIP files.  In fact, you
      can play-back any file you want.  You could load any simple text
      file, ANSI picture image, or other such thing.  When loaded, the data
      is not sent to the host; it is strictly echoed on your local screen.
      If the file is a .RIP file, it will replay any graphics that were in
      the file and if any Mouse Regions are defined, it will create those
      fields for you as well, thus allowing you to pop-up dialog screens or
      other such things that are not built-in to RIPterm normally.

      Each "local RIP playback" variable you enter will search for the .RIP
      file in the current host's icon directory.  If it cannot find the
      file in that directory, it will check the ICONS\ directory.






     =====================================================================
     ==                           POP-UP LISTS                          ==
     =====================================================================

     Any place that you can use a Text Variable, you can take advantage
     of a unique feature of RIPscrip - Popup Pick-Lists.  A Popup Pick-
     List is simply a list that pops up allowing you to choose from one
     of several available values.  Whichever entry in the list you choose
     will be inserted into your Keystroke Macro in place of the List
     Definition.

     In order to use Popup Pick-Lists, you must define the List in the
     text of your Host Command.

     A List is created by putting the special List instructions inside of
     two parenthesis (( and )).  The list instructions consist of an
     optional Question, followed by one or more entries to put in the
     List.  For example, ((Send Email to?::Sysop,Cosysop,Joe)) says to
     Pop-Up a list asking you "Send Email to?", giving you the choices of
     "Sysop", "Cosysop", and "Joe".

     By default, if you hit <ESCAPE> instead of picking an entry in the
     list, then nothing will be inserted into the text of your Command.
     You can indicate that the user MUST pick an entry by puttin an
     asterisk (*) at the beginning of the question.  For example,
     ((*Send Mail to?::Sysop,Joe)).  This would make it so that the User
     MUST choose either SYSOP or JOE.

     In the previous examples, SYSOP, COSYSOP and JOE are the actual text
     responses that are inserted into your Macros.  These commands are
     also the same things that are displayed in the Listing.  If you want
     to use something else instead of the actual "return text", you can.
     When you enter the List Entry, add a @description to the end of it.


        For example, ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe))


     One final feature of Popup Pick-Lists allow you to specify a hotkey
     for each entry in the List.  For example, if you wanted the first
     character of each entry to be hilighted (thus allowing you to select
     that character to activate the entry), simply put a tilda (~) or an
     underline (_) before and after the keystroke.  For example "_S_ysop"
     would hilight the "S" in "Sysop".  You can hilight more than one
     character, but only the first one will be the active hotkey.  If you
     omit the second tilda or underline, then the remainder of the
     description will be hilighted.

        NOTE: If you use a Tilda or an Underline in the actual Text
              Response command (not the description), then those
              characters will be automatically inserted into your
              Macro when it gets transmitted to the BBS.  This is
              probably not what you would want to do.  Bottom line,
              only use Hotkey features on List Entries where you
              specify a Description!

              If you do not specify a Question, then the List will
              ask you:


                  "Choose one of the following:"


              You may specify up to twenty List Entries for any
              one list.


     Examples:

       ((Send E-Mail to?::Sysop,Joe,Mike))
       ((*Send EMail to?::Sysop@The Head Honcho,Joe,Mike@My Brother))
       ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother))
       ((Sysop,Joe,Mike,George))





     =====================================================================
     ==                     HOST COMMAND "TEMPLATES"                    ==
     =====================================================================

     This feature is somewhat complex in nature, but ultimately powerful
     in the long run when creating interactive mouse-driven GUI systems.

     Often times you might want a Button on your screen to do one thing
     in one situation, but to do something completely different in
     another situation.  In the past, this required having a separate
     menu file for each different function that this Button needs.  This
     cumbersome method is "history" with Command Templates.

     Command Templates are probably best described with a brief example.
     Let's say that you have a menu screen for reading and writing
     messages in your public message forums.  On this menu, you can have
     buttons for each forum on your system, and at the same time have
     buttons for READ, WRITE, ERASE, MODIFY, etc.  Now, how can you make
     the READ/WRITE/etc buttons work differently for each Forum?


                                   Templates!


     To further refine our example, let's say that if you click on the
     button for Forum #1, it should send the command "S FORUM1" to the
     host to select that forum.  After that, simply clicking on the
     READ or WRITE buttons will read through the current section.  But,
     what if you want to interactively move about on the menu quickly?
     Make each of the Forum selection buttons define a template.  Each
     template will instruct RIPscrip how to process the other Buttons.

     In the above example, the Forum #1 button would define a template
     like this:


                                 S FORUM1 $?$^m


     This Template will return "S FORUM1" followed by the Host Command
     for whichever button is clicked, followed by a carriage return.
     The special text variable $?$ is only used in Command Templates,
     and is used to indicate "insert the text into the template here".
     It references the text of some other button that was clicked that
     is stuffing it's data INTO this template.


     CHARACTERISTICS OF TEMPLATES
     ----------------------------
        Before you can actually go about defining templates, you
        need to know how they work, interact and how other functions
        interact with templates.

        You are allowed up to 36 different templates, each of which
        can be different and can all be active at the same time.  Each
        of the 36 templates correspond to a Button Group (see the
        Button Command).  Templates can be defined and/or activated
        in any order.  In other words, you can have a template #1, 5
        13 and 32, but none of the others defined.  Templates remain
        defined until re-defined by another template.


     DEFINING A TEMPLATE
     -------------------
        To create a template, when asked for a Host Command, simply
        type in the Template similar to the following:


               [5:]S FORUM1 $?$^m


        The [5:] at the beginning of the command indicates that you
        wish to create template #5 with the following text as the
        template.  Remember, a $?$ is considered a "macro" that will
        insert some text into this template from some other source.
        Valid template numbers are 0-9, A-Z.  So, with this in mind,
        all of the template definitions are valid:


               [0:]S FORUM1 $?$^m
               [9:]S FORUM2 $?$^m
               [G:]S FORUM3 $?$^m


     USING TEMPLATES
     ---------------
        When you want to make a button "feed its command" into a
        template, you do so in a format similar to defining a
        Template, but with a subtle difference.  Don't include
        the colon (:) in the template reference.  An example of
        this would be the following:


               [0]HELLO


        This says, take the text "HELLO" and feed it into template
        number 0, and send the final result to the BBS.  Note how
        simple it is to create and reference templates by either
        using a colon or omitting it.

        If you do not specify a Template reference in the format
        [#] at the beginning of your Host Command, it will be
        considered to be a "normal Host Command" that does not
        get stuffed into any templates.  For completeness, you
        may specify []HELLO to send the word "HELLO" to the BBS
        without going through any templates (a "null" template).
        So in other words, using a [] or using nothing at all is
        the same thing, don't use any templates for this Host
        command.


     CHAINING ONE TEMPLATE RESPONSE INTO ANOTHER (TEMPLATE CHAINING)
     ---------------------------------------------------------------
        In the preceding examples we showed how you can feed the
        Host Command of one button through a single Template
        definition.  This is the "simplest case" of template
        processing.  As part of the "big picture" of templates,
        you can actually "chain" the input of one template into
        another template, into another, so on and so forth and
        then transmit the result of all composite template stuffing
        to the Host as one big command.  After all is said and done
        with template processing, the text buffer sent to the host
        can be anywhere from 0-4095 bytes in length.

        To chain one template into another, follow a format similar
        to the following:


               [0372]HELLO


        This will feed the word "HELLO" into template #0, then the
        result into template #3, then that result into template #7,
        then finally the result will be stuffed into Template #2.
        The final result will be then transmitted to the BBS.

        You may specify from 0-36 different templates in any one
        chaining operations.  You MAY use the same template more
        than once in the same chain, like the following:


               [0370]HELLO


        Note, that template #0 is used twice, both at the beginning
        and the end of the processing.  This feature, potentially
        dangerous, is provided for completeness and flexibility.


     EMBEDDED TEMPLATES
     ------------------
        You can embed the contents of one Template into another
        template (or into a Host Command) by using the special
        Text Variable $?x$ where "x" is the Template number to
        insert.  This command functions much like the insert-text
        variable $?$ does, but gives you a great deal more power
        and flexibility.

        If you specify to embed one template inside another, the
        embedded template can contain text variables, pick-lists
        and other such things.  It can even have another embedded
        template in it as well, but that sub-embedded template
        cannot have ANY text variables, or any special commands,
        not even control characters!

        To sum it up, an embedded template can have anything you
        want in it, including other embedded templates.  All
        text variables in an embedded template are expanded, as
        are pick lists, control characters and the like.  If you
        have an embedded template INSIDE an embedded template,
        the deepest embedded template will have NO text variable
        processing done on it - i.e., the text is sent to the
        host verbatim, exactly as it appears in the template.

        If a template that is referenced is not yet defined, the
        template embed command will be skipped (i.e., blank) providing
        that the embedded template doesn't refer to a Radio Group.
        Radio Groups are "dependencies" in this manner.  Anything
        that tries to embed a Template from a Radio Group will
        not be processed if a template in that area hasn't been
        defined yet.  Embedded templates from Checkbox Groups can
        be skipped if none of the check-boxes are active.


     TEXT VARIABLES, PICK-LISTS AND CONTROL CHARACTERS IN TEMPLATES
     --------------------------------------------------------------
        You may use Text Variables, Pick-Lists and Control Characters
        anywhere in any template definition, or reference.  You are
        limited such that, a text variable is translated to its
        real value when the template is being processed, not after
        all templates are processed.  The net result of this is,
        you cannot use one template to construct another template's
        pick-list, text variables, or the such.

        In other words, you cannot "nest" text variable definitions,
        pick lists, or control characters.  You can have these
        commands in any or all templates used in a given template
        chain, but they are independent of each other.


     EXAMPLES OF SOME TEMPLATE-CHAINS
     --------------------------------
        Below are several examples of different template setups.
        These are intended to give you ideas on how templates
        may be used:

          Example #1:

            [0:]D $?$ Z^m       ... Used to download a file with Zmodem
            [1:]D $?$ X^m       ... Used to download a file with Xmodem

            [0]FILENAME.ZIP     ... Use this with #0 to download Zmodem
            [1]FILENAME.ZIP     ... Use this with #1 to download Xmodem

            In this example, template #0 is used for downloading with
            Zmodem.  Template #1 is for downloading with Xmodem.
            Depending on which FILENAME.ZIP button you click on, you
            might download it with one protocol or with another.  It
            all lies on which template you reference.  The text
            transmitted to the BBS if you clicked on the buttons could
            be either:

                    D FILENAME.ZIP Z^m
              or,   D FILENAME.ZIP X^m


          Example #2:

            [0:]D $?$           ... Make this the "DOWNLOAD NOW" button

            [1:]$?$ X^m         ... Radio Button #1   (X-Modem)
            [1:]$?$ Y^m         ... Radio Button #2   (Y-Modem)
            [1:]$?$ B^m         ... Radio Button #3   (Y-Modem Batch)
            [1:]$?$ Z^m         ... Radio Button #4   (Z-Modem)

            [01]FILENUM1.ZIP    ... Button to download file #1
            [01]FILENUM2.ZIP    ... Button to download file #2
            [01]FILENUM3.ZIP    ... Button to download file #3

            This example is a bit more involved.  It brings the concept
            of "radio buttons" into the picture.  This is something
            that is part of the Button command.  A Radio button is
            like having a list of options on your screen, only one
            of which can be active at any one time.  When using
            templates with Radio buttons, you can quickly and elegantly
            define a menu that can do one thing in one mode, or
            something totally different in another mode.  An example
            of the above menu might be as follows:


                 Protocols:                Download which file?
                    __                        __
                   |\/|                      |  |
                   |/\| X-Modem              |  | File #1
                    --                        --
                    __                        __
                   |  |                      |\/|
                   |  | Y-Modem              |/\| File #2
                    --                        --
                    __                        __
                   |  |                      |  |
                   |  | Y-Modem (batch)      |  | File #3
                    --                        --
                    __
                   |  |
                   |  | Z-Modem         _______________________
                    --                 |                       |
                                       |  BEGIN DOWNLOAD NOW!  |
                                       |_______________________|


     MORE ABOUT TEMPLATES
     --------------------
        When you use the $?$ text variable inside a template definition,
        you are not limited to using it only once.  In fact, you can use
        it as many times in your template definition as you wish.  This
        can be useful under many circumstances where the user might have
        to enter the same thing twice.

        In the preceding example #2, a group of Radio Buttons was used
        on the right side of the screen to determine which file should
        be downloaded.  In that example, there was no ability to specify
        an arbitrary filename to download.  You were only allowed to
        download one of three given files.  What would be perfect, would
        be to have the ability to pop-up a question to the user asking
        what filename they wanted.  The solution is easy, insert a
        text-variable that hasn't been defined yet!  To illustrate, the
        above example could be modified to accomodate this as follows:

            [0:]D $?$           ... Make this the "DOWNLOAD NOW" button

            [1:]$?$ X           ... Radio Button #1   (X-Modem)
            [1:]$?$ Y           ... Radio Button #2   (Y-Modem)
            [1:]$?$ B           ... Radio Button #3   (Y-Modem Batch)
            [1:]$?$ Z           ... Radio Button #4   (Z-Modem)

            [01]FILENUM1.ZIP    ... Button to download file #1
            [01]FILENUM2.ZIP    ... Button to download file #2
            [01]FILENUM3.ZIP    ... Button to download file #3
            [01]$FILENAME$      ... Button to download ANY file

        The screen might appear something like this:

                 Protocols:                Download which file?
                    __                        __
                   |\/|                      |  |
                   |/\| X-Modem              |  | File #1
                    --                        --
                    __                        __
                   |  |                      |\/|
                   |  | Y-Modem              |/\| File #2
                    --                        --
                    __                        __
                   |  |                      |  |
                   |  | Y-Modem (batch)      |  | File #3
                    --                        --
                    __                        __
                   |  |                      |  |
                   |  | Z-Modem              |  | Enter Filename
                    --                        --

                               _______________________
                              |                       |
                              |  BEGIN DOWNLOAD NOW!  |
                              |_______________________|


        Note the addition of the "Enter Filename" button.  If the user
        clicked on that button, it would first try to replace $FILENAME$
        with a text variable.  It will find that such a variable does
        not exist, and will then pop-up the following question on the
        screen:

                       _____________________________
                      |                             |
                      |       Enter "FILENAME"      |
                      |   _______________________   |
                      |  |                       |  |
                      |  |_______________________|  |
                      |                             |
                      |_____________________________|


        If the user typed in "DEMOFILE.TXT", then that filename is
        inserted where $FILENAME$ was located, then it is piped through
        template #0, resulting in:


                    D DEMOFILE.TXT


        The result of that is then stuffed through Template #1 which
        gives the following return string sent to the BBS:


                    D DEMOFILE.TXT Z^m


        This is only an example, your mileage may vary.




     =====================================================================
     ==                TEXT VARIABLE CREATION, AND QUERY                ==
     =====================================================================

     As mentioned in preceding sections, Text Variables were described
     as either "pre-defined" variables, or as "User Variables".  Pre-
     defined variables are variables that RIPscrip products know things
     about "out of the box".  They will always know what the variables
     mean, from the day you install them.  User Variables on the other
     hand, are variables that you, the user of RIPscrip products define,
     and teach the system information.


     WHAT ARE USER VARIABLES?
     ------------------------
        A User Variable is a Text Variable that RIPscrip doesn't
        already know exists.  They are custom-defined text variables
        that contain information that the RIPterm user will fill-in.
        If a variable already contains information, a BBS will be auto-
        matically told [IF TOLD TO DO SO] what that variable contains
        without the user having to intervene (i.e., transparent informa-
        tion exchange).

           Examples of Text Variables might be:

               $FULL_NAME$    ... What is your full name?
               $COMPANY_NAME$ ... What company do you work for?
               $AGE?          ... How old are you?
               $DATEOFBIRTH$  ... What is your Date of Birth?
               $PHONENUMBER$  ... What is your Day-time phone number?

        User Variables will "keep track" of these responses for you,
        on the Terminal program end.  You can tell the Terminal to
        store these values "permanently" in a disk-file, or they may
        be active only during the current online session, or they
        may be defined as "temporary" where they are not stored for
        more than a brief moment.

        Note, this ability is configurable so that information exchange
        can be either interactive, or automatic.  Automatic transfer
        of information does NOT prompt the user with the information
        unless the variable has not yet been defined.  If it has not
        been defined, a pop-up question will appear asking the user
        a particular question, thus defining the text variable.

        If the exchange is "interactive", the data is displayed in a
        pop-up editor box, asking you if the information is correct.
        If it is, simply tap <ENTER> and the retrieved information is
        sent to the BBS for you.  If it is not correct, or it has not
        been created yet, just type it in and tap <ENTER> and it will
        be saved automatically, and sent to the BBS all at once.


     HOW CAN USER VARIABLES BE IMPORTANT?
     ------------------------------------
        Let's take an example.  Let's say you are a System Operator
        of a large RIPscrip BBS.  As you have read, RIPscrip can take
        advantage of "database like" ability on the terminal-end of
        the communication.  If you can alter your BBS to ask questions
        with RIPscrip "text variables" built in, you can have the
        terminal calling your system automatically fill-in questionaires
        on your system.  Imagine if a user could "sign-up" on your BBS
        without having to type more than a single keystroke (i.e., "YES,
        this information is correct").  With User Text Variables, you
        can do this very thing.


     CREATING USER VARIABLES
     -----------------------
        There are two ways of defining User Text Variables in RIPaint.
        You can use either "Define Text Variable" commands, or you
        can use Text Variable Queries, as described in the next
        section.


     DEFINING TEXT VARIABLES
     -----------------------
        The RIPscrip command "Define Text Variable" is by definition,
        an interactive command with the User.  The RIPscrip command
        will attempt to define a "User Variable".  This Variable is
        some piece of information that the System Operator deems
        important.  You may specify a question, a default response,
        and how many characters long the response may be.

        Once the "define command" has been sent to the Terminal, it
        [the terminal] pops up an appropriate question box on the
        User's screen asking him the desired question that should be
        saved to a particular Text Variable.  If you did not specify
        a question, a suitable "default" question will be displayed.

        Once the User has entered his response, it is recorded and
        saved.  How long it is saved depends on how the BBS told
        the terminal.  The BBS can tell the terminal "save this
        on your hard disk forever".  The BBS may also tell the
        terminal, "don't save this to disk, but remember this value
        until your connection with our BBS is lost".  You also have
        the option of saying, "don't remember this value at all,
        just simply pop-up a question on-screen, and send the value
        to me NOW - i.e., don't save it at all - just enter it and send
        it to the BBS).


     QUERYING TEXT VARIABLES
     -----------------------
        Now that you know how to define information on the terminal,
        you need to know the last method of asking the terminal
        about text variables.  This feature is called "data query".

        Data Query is a generic "query" command that can ask the
        terminal one or more questions, and tell it how to transmit
        the information back to the host.  This command is for use
        in non-button situations where you do not want to wait until
        the user clicks on a button to get your data back.

        A Data Query is actually a special RIPscrip command that can
        be used to ask the contents of one or more Text Variables.


     EXAMPLES OF TEXT VARIABLE QUERY
     -------------------------------
       Let's take a simple example.  Let's say that you wanted to ask
       the Terminal program some address information.  You could do
       so with the following query (remember, the query also tells
       the terminal HOW to send the data back to the BBS):


          $FULL_NAME$^m$COMPANY$^m$STREET_ADDR$^m$CITY$, $STATE$ $ZIP^m


       This would query the terminal the contents of 6 text variables,
       and format them in a manner similar to any normal address on
       an envelope.  The results of this query might send the following
       back to the host (again, your mileage may vary):


          Jeff Reeder
          TeleGrafix Communications, Inc.
          16458 Bolsa Chica #15
          Huntington Beach, CA 92649


       If a text variable is queried, and it has not been defined yet,
       a pop-up question will appear asking the user to fill-in the
       information.