home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / SX54H1.ZIP / XPRIP.DOC < prev    next >
Text File  |  1994-06-04  |  17KB  |  368 lines
  1.                 -------------------------------------------
  2.                        RIP SUPPORT FOR SILVER XPRESS
  3.                (c) copyright 1993-94 by Santronics Software
  4.                            All rights reserved
  5.                 -------------------------------------------
  6.                           DRAFT DOCUMENT 5.03
  7.  
  8. This document describes the specification for RIP support in Xpress.
  9. RIP Xpress Documentation is still evolving.  Please feel free to provide
  10. comments on how to better describe RIP and its usage with Silver xpress.
  11.  
  12. Silver Xpress supports the new GUI system called Remote Imaging Protocol,
  13. otherwise known as RIPScript or just RIP.  It was the first major off-line
  14. mail door to support RIP.
  15.  
  16. For the most part, Xpress did not require any change for minimal RIP
  17. support, but Xpress was enhanced to ensure it was 100% Rippable!
  18.  
  19. As a sysop of Xpress, you have two options for RIP Support:
  20.  
  21.   1) You can use the built-in RIP logic in Xpress, or
  22.   2) You can totally customize your own RIP screens or scenes.
  23.  
  24. We made it easy for you, and Xpress is RIP-Ready right out of the BOX!!
  25. Simply enable Xpress to use the BUILT-IN RIP options and you are ready to
  26. RIP!
  27.  
  28. If you want to use the built-in mode and still paint some of the screens,
  29. you can do so!  If you want to paint ALL of the screens, you must
  30. disable the built-in option.
  31.  
  32. This document will explain the points in the Silver Xpress package where
  33. certain files will be displayed.  It will help guide your RIP design for
  34. Xpress.
  35.  
  36. New command line switches:
  37. --------------------------
  38.  
  39.      /R-      Disable RIP detection all together (default).
  40.      /R+      Enable  RIP detection.
  41.      /R       Prompt the user for RIP usage (and detection).
  42.      /RLE     Display RIP script at local console.
  43.      /RMx     Menu layout number (enable built-in RIP logic).
  44.      /RKM     Keep menus from clearing.
  45.  
  46.      Note:    RA 2.00. PROBOARD, PCBOARD, WILDCAT! passe the RIP ON flag in
  47.               the Door Drop File.  No switch required.
  48.  
  49. RIP Detection
  50. -------------
  51.  
  52. Silver Xpress is designed to detect a RIP terminal if RIP detection is
  53. enabled in XPADM or if the /R+ or /R is used.
  54.  
  55. If the BBS tells Xpress RIP is enabled, Xpress will try to detect RIP.
  56.  
  57. If the environment string RIP=ON is available, Xpress will try to
  58. detect RIP.
  59.  
  60. If the user has set his "NO RIP GRAPHICS" to YES, Xpress will not
  61. bother at all with RIP and RIP detection.
  62.  
  63. New menu commands (macros) for users to use while in Xpress.
  64. ------------------------------------------------------------
  65.  
  66.      \RIPON   disable RIP
  67.      \RIPOFF  enable  RIP
  68.  
  69. General discussion about using Xpress in RIP Mode
  70. -------------------------------------------------
  71.  
  72. If you don't understand what RIP is, let me try to sum it up in so many
  73. words:
  74.  
  75. Under normal situations, like ANSI mode, Xpress displays files to color
  76. your screen locally and sends the same ANSI information to your remote
  77. user.  The user who has an ANSI terminal program, will see color because
  78. their terminal program is interpreting the ANSI codes.
  79.  
  80. The same logic applies to RIP.  If the user has a RIP terminal, RIP codes
  81. will instruct it to paint and draw pretty pictures in graphic mode!
  82.  
  83. However, please note, the Xpress mail door is not graphical and, hence, the
  84. local screen on your machine will not be graphical.  If the /RLE switch is
  85. used, you will see the "junk" rip codes on your local screen, otherwise,
  86. all you see is the normal Xpress screens.
  87.  
  88. Now here lies the major or key technology in RIP (in my opinion).
  89.  
  90. Normally, under ANSI or just plain TTY mode, the user's terminal program
  91. will accept any keyboard input and simply send it to the remote host
  92. (Xpress).  The terminal does no interpretation, no translation, nothing.
  93. It just sends it. Xpress will read the input and act on it.
  94.  
  95. In RIP mode, it is possible to PAINT a picture with MOUSE buttons for each
  96. option available to Xpress.  The key feature is that you can instruct the
  97. RIP terminal what to send to the HOST when the BUTTON is clicked!!!
  98.  
  99. If you don't understand this, it is best that you study this important
  100. and key technology feature in RIP if your plan to customize Xpress.  Once
  101. you understand this, creating RIP screen logic for your system will become
  102. easier.
  103.  
  104. How RIP is implemented in Silver Xpress
  105. ---------------------------------------
  106.  
  107. All Xpress VCC display files can now have a RIP file counterpart with the
  108. extension RIP.  For example, WELCOME.VCC and WELCOME.RIP.  This includes
  109. all the HLP files in the HELP directory.
  110.  
  111. In RIP mode, if a corresponding RIP file is found, it will be send to the
  112. RIP terminal for RIP interpretation.
  113.  
  114. Both the VCC information and the RIP information is sent to the RIP
  115. terminal.  It is up to your RIP design to decide if you want the user to
  116. see the text information (turning off or on Rip Text Windows).  The default,
  117. out-of-the-box, RIP design in Xpress has text windows normally turned off at
  118. the terminal side.  This means the user does not see the VCC information.
  119.  
  120. Each menu that is defined for Silver Xpress has a HELP keyword to define
  121. the help file to be displayed if the user hits the question mark.  In
  122. RIP mode, if a corresponding RIP file is found, it will be displayed as
  123. well.  This RIP help file must be in the HELP directory.
  124.  
  125. The HELP keyword also defines the VVC, hence RIP, file that can be
  126. displayed as a replacement for the current menu.  These files are located in
  127. the MISC directory.  So it is possible to have two files with the same
  128. name, but in separate directories.  Keep that in mind.
  129.  
  130. Remember, if a VCC menu file is found, Xpress will not use the menu
  131. ITEMS defined in XPMENU.CTL for that particular menu for display.  It will
  132. display the VCC menu file instead.  If a corresponding RIP file is
  133. found, it will be used for RIP graphics (note:  this is good when you
  134. don't have the built-in menu system enabled).
  135.  
  136. There are new RIP keywords in the XPMENU.CTL control file:
  137.  
  138. RIPTITLE defines the title for the built-in menu system.
  139.  
  140. RIP is used for each menu item which defines the words to use for the
  141. built-in menu RIP controls in Xpress.
  142.  
  143. Each menu option in Xpress has a unique menu code (see documentation).
  144. If a RIP file is found for a menu code, it is sent to the RIP terminal.
  145. For example, the menu action code for the GOODBYE option is 134.  Xpress
  146. will display the RIP file 134.RIP (if found) when this option is hit.
  147.  
  148. At various points in Silver Xpress, there is built-in logic to display RIP
  149. commands (only if enabled).  You will find if you change options around
  150. alot, you would want Xpress to have full control of what is displayed to
  151. the user, including menu options, pick list options, etc.  You may have
  152. some Xpress menu options with high security values.  If you use static
  153. screens, users will see the options but still not have access to them.
  154. With the built-in menu RIP control, Xpress will only show the right
  155. options to the user.
  156.  
  157. As you can see, Xpress has layed down the groundwork for you to
  158. design a very powerful Xpress RIP application.  You can use any of these
  159. display logic combinations to get the most effective RIP screen design.
  160.  
  161. The section called RIP XPRESS LAYOUT explains all the files and special
  162. cases for RIP at all the key points in Silver Xpress.  It will help guide
  163. your design if you intend to customize RIP in Xpress.
  164.  
  165. RIP Initialization in Silver Xpress
  166.  
  167. Before the INIT.VCC/RIP file is displayed, a RIP detection is performed.
  168. The very first string written, "Initializing Silver Xpress...." was removed
  169. from the language file and put into the INIT.VCC display file,
  170.  
  171. THE RIP XPRESS LAYOUT
  172. ---------------------
  173.  
  174. Each and every MENU ACTION CODE in Silver Xpress (SEE XPMENU.CTL) has
  175. a check for a RIP file.  In otherwords, when a user selects a Xpress
  176. menu command, the corresponding action code is checked for a RIP file.
  177.  
  178. For Example:
  179.  
  180.   To display the user list, the action code 101 is executed in Silver
  181.   Xpress.  If a 101.RIP file is found, it will be sent to the RIP Terminal.
  182.  
  183. This logic permits you to do almost anything you want.  The standard 1??.RIP
  184. files which came with Silver Xpress are used mostly to switched to TERMINAL
  185. mode in tight situations where RIP was difficult to implement at this time.
  186. In fact, this method is used to display the HLP files at each menu.  The
  187. action code 132 is used to display the help file.  The 132.RIP file is used
  188. to switch the user into terminal mode.
  189.  
  190. The following table below shows the files Xpress expects (by default) to
  191. display to the user.
  192.  
  193. For each VCC file display, a corresponding RIP file can be displayed.
  194. There are also some points in the program where RIP files are displayed,
  195. and no VCC file.  The files listed below without an extension are VCC
  196. files, which means a corresponding RIP file can be displayed. If the
  197. file has a RIP extension, no normal VCC is available at that point.
  198.  
  199. Xpress has built-in RIP logic at various points.  If the built-in column
  200. indicates the option is built-in, no RIP file will be displayed for
  201. that section.  It will override the RIP file (but not the VCC file).
  202. (!! you may want to allow the display as it !!)
  203.  
  204.                                           FILE              BUILT-IN
  205.                                           --------------------------
  206.   Initial Start Up                        INIT
  207.   Welcoming User                          WELCOME
  208. * Asking User for Door Password           DOORPWD.RIP
  209. * Bad Password Entered                    BADPWD
  210.   New User Information                    NEWUSER
  211.   News                                    NEWS
  212.   Scanning Mail
  213.       Retry an abort download             RETRYDL.RIP
  214.       vacation mail check (see below)
  215. *     No Areas Selected, Abort            NOAREAS.RIP
  216.       beginning scan/dl process           BEGSCAN.RIP
  217.       summary table top                   MSTOP.RIP
  218.       summary table bot                   MSBOT.RIP
  219.       flex prompt                         FLEX.RIP
  220.       User Aborted Download After Scan    UPDATELR.RIP
  221.       end of scan/dl process              ENDSCAN.RIP
  222.   Uploading Mail
  223.       begining of mail upload session     BEGUPLD.RIP
  224.       beginning of upload/receiving file  BEGRCVD.RIP
  225.       end of upload/receiving file        ENDRCVD.RIP
  226.       End of mail upload session          BEGUPLD.RIP
  227.   Download a file(s)
  228.       beginning of dnload process         BEGDNLD.RIP
  229.       download prompt                     DLPROMPT.RIP  and built-in
  230.       end of dnload process               ENDDNLD.RIP
  231.   Vacation Saver
  232.       Toggle Vacation Saver               XPVSAVER
  233.       No Mail                             NOVAC
  234.       Mail available                      VACPAC.RIP
  235.   Picking an Archiver                     ARCHIVER.RIP  or  built-in
  236.   Picking an Protocol                     PROTOCOL.RIP  or  built-in
  237.   File Requesting                         INITFREQ.RIP
  238.   Area Selection Section
  239.      Enter   Section                      BEGAREA.RIP
  240.      Exiting Section                      BEGAREA.RIP
  241.   Hanging Up From Xpress                  GOODBYE
  242.   Exiting Xpress                          RIPDONE.RIP
  243.   User activated RIP OFF                  TURNROFF.RIP
  244.   User activated RIP ON                   TURNRON.RIP
  245. * Abnormal Exit/Abort from Xpress         ABORT.RIP
  246. * Critical Error Abort                    CRITICAL.RIP
  247.   ViewLog Prompt                          VIEWLOG.RIP
  248. * Display Macros                          MACROLST.RIP
  249.  
  250. * - Inplemented in Version 5.03
  251.  
  252.  
  253.  
  254. Other RIP or VCC files.
  255.  
  256.   Xpress Dynamic Menus
  257.      Start of Menu System                 BEGMNUx.RIP
  258.      Each menu (dynamic names)            dynamically displayed.
  259.      clearing a menu                      CLRMENU.RIP
  260.      End of Menuing System                ENDMNUx.RIP
  261.  
  262.  
  263.   Continue Prompts          ON            HITKEY1.RIP
  264.                             OFF           HITKEY0.RIP
  265.   Generic MoreYN Prompt     ON            MOREYN1.RIP
  266.                             OFF           MOREYN0.RIP
  267.   Goodbye prompt                          ASKBYE.RIP
  268.   Final Exiting of Xpress                 RIPDONE.RIP
  269.   No Access to Option                     NOACCESS.RIP
  270.   Changing Last Read Pointers             CLRPDATE.VCC
  271.   Getting User Door Password              SETDPWD.RIP
  272.   Getting User Reader Password            SETRPWD.RIP
  273.   CHAT  ON                                CHATON.RIP
  274.   CHAT  OFF                               CHATOFF.RIP
  275.  
  276. NOTES:
  277.  
  278. RIPDONE.RIP is normally required to make sure RIP graphics are turned off
  279. before returning to the non-ripping BBS.  Your EXIT RIP file may get erased
  280. quickly so it's probably not a good idea to use an EXIT RIP.  Also, your
  281. BBS, which has limited RIP support, may require that an external DOOR does
  282. not turn off RIP.  If this is the case, either remove this file or change
  283. the logic.  (Version 5.03 now has option to Call to his file. No need to
  284. delete).
  285.  
  286.  
  287.                   ---------------------------------------
  288.                   USING THE BUILT-IN RIP SYSTEM IN XPRESS
  289.                   ---------------------------------------
  290.  
  291. Each Xpress menu defined in XPMENU.CTL can have a corresponding RIP file
  292. displayed when each menu is activated. The name of the RIP file is also the
  293. name of the HELP file defined for the menu.  So you have the option to
  294. create a RIP file for each menu defined.  However, please note, if you
  295. change your menu, you will have to modify the corresponding RIP file.
  296.  
  297. One of the flaws with this logic is that scenes or screen menus will not be
  298. alike from user to user.  Such is the case with menus.  Silver Xpress has a
  299. security system for menu options.  It is possible some menu options will not
  300. be available to the user based on their security.  If we stayed with static
  301. RIP scenes, the menu options would be shown but not really available to the
  302. user.  You should realize this pretty fast even with your own BBS menus.
  303.  
  304. The solution is to utilize the information in Xpress's menu database and
  305. allow the system to dynamically redraw the menus for you.
  306.  
  307. With this unique, built-in RIP menuing system in Silver Xpress, the menu
  308. RIP files will not be displayed.  Instead, only a few RIP files are used to
  309. draw an outline of the menu and Xpress will handle the rest of the drawing
  310. for the menu options, titles, etc., thus assuring valid menu options are
  311. shown to the user.
  312.  
  313. The basic goal here is to minimize any work you have to do with RIP scenes
  314. or scripts.  Let Xpress do the job for you!  The scenes may not be fancy,
  315. but at least you won't have to be changing menus screens around every
  316. time you modify the Xpress menus.
  317.  
  318. To offer you some flexibility, Xpress allows you the ability to define the
  319. the menu layout.  One is supplied, and others will be released as they come.
  320.  
  321. MENU LAYOUT #1 ENABLED:
  322.  
  323.   ┌─────────────────────────────────────────────────────┐ <-- BEGMNU1.RIP
  324.   │ Silver Xpress/RIP                        (copyright)│
  325.   ├─────────────────────────────────────────────────────┤ <-- NEWMNU1.RIP
  326.   │ ┌─────────────────────────────────────────────────┐ │
  327.   │ │                   MENU TITLE                    │ │
  328.   │ └─────────────────────────────────────────────────┘ │
  329.   │   O menu option    O menu option    O menu option   │ <-- normal
  330.   │   O menu option    O menu option    O menu option   │     buttons
  331.   │   O menu option    O menu option    O menu option   │
  332.   │   O menu option    O menu option    O menu option   │
  333.   │   O menu option    O menu option    O menu option   │
  334.   │   O menu option    O menu option    O menu option   │
  335.   │  =================================================  │
  336.   │   QUIT  GOODBYE  HELP                               │ <-- special
  337.   │  =================================================  │     buttons
  338.   │  status line                                        │
  339.   ├─────────────────────────────────────────────────────┤
  340.   │RIP TERMINAL STATUS LINE                             │
  341.   └─────────────────────────────────────────────────────┘
  342.  
  343.  
  344.   BEGMNUx.RIP  Displayed at the start of the menu system.  This is used as
  345.                the Basic Screen outline.  It should have a RIP reset and No
  346.                Text Windows.
  347.  
  348.   ENDMNUx.RIP  Displayed at the end of the menu system.  Usually isn't
  349.                necessary since, by then, other displays will take over,
  350.                such as goodbye or exit.
  351.  
  352.   For each menu, the following files are displayed:
  353.  
  354.   NEWMNUx.RIP  This display is basically for clearing the menu system.
  355.                It draws the menu title bar and the horizontal lines.
  356.  
  357.   CLRMNUx.RIP  You can define this but it does nothing for now.  You can
  358.                use it to clear the menu area if you like.
  359.  
  360.   As Xpress loops thru its menu options, it will calculate the display
  361.   positions for the options and create buttons for each menu.  These normal
  362.   buttons are displayed in the middle section of the screen.  Special buttons
  363.   are also displayed. Special buttons are _QUIT, _GOODBYE and _HELP.
  364.  
  365.   The status line is used to display any one line messages that need to be
  366.   displayed.  Xpress does this automatically.
  367.  
  368.