home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / developmen / ohs20 / OHS.TXT < prev    next >
Text File  |  1994-03-10  |  11KB  |  301 lines
  1.                           OPL Help System
  2.                             Version 2.0
  3.                   Copyright (c) Tom Dolbilin 1994
  4.  
  5.  
  6. Introduction
  7. ============
  8.  
  9. OPL Help System is intended to be used by OPL developers to create
  10. professionally-looking help screens in OPL programs. OPL Help
  11. System 2.0 includes two files HCP.OPO (version 1.2) and
  12. SYS$HELP.OPO (version 2.0).
  13.  
  14. HCP.OPO is the help compiler. It reads in a text source file (TXT)
  15. and creates the help file (HLP).
  16.  
  17. SYS$HELP.OPO is the help driver, which you call from within your
  18. program. It reads the help file and displays it on the screen. You
  19. have to include it in your distribution package. You can use the
  20. Help System in your own programs free of charge even if those
  21. programs are shareware or commercial. Source code for SYS$HELP.OPL
  22. is included.
  23.  
  24.  
  25. Usage Guidelines (IMPORTANT)
  26. ============================
  27.  
  28. OPL Help System was designed with limited disk space resources in
  29. mind. Therefore, it is strongly recommended that you follow a few
  30. simple rules if you decide to use it with you program:
  31.  
  32. 1.   You program should be able to run without SYS$HELP.OPO and/or
  33.      .HLP files installed. Give the user the freedom of discarding
  34.      Help if they don't need it.
  35. 2.   Because SYS$HELP.OPO can be used by more than one program, it
  36.      should be put in a common directory, namely \OPO. Most people
  37.      already have this directory so they won't have to create it.
  38.      Because SYS$HELP.OPO starts with "SYS$", it will not appear
  39.      in the list under the RunOPL icon.
  40. 3.   The source code is provided so that you can see how it works
  41.      before using it in your program. If you decide to alter it,
  42.      please rename it. You can, of course, embed SYS$HELP.OPO into
  43.      your main program file, but it's discouraged because of the
  44.      reason #1.
  45.  
  46.  
  47. Creating the Source File
  48. ========================
  49.  
  50. Source file is a plain text file. You can use the OPL editor or a
  51. Text alias for Word to create text files. The format of a help
  52. source file is very simple.
  53.  
  54. Go to the System Screen and press the Help key. You will get the
  55. first-level help screen which has a TITLE "System screen" at the
  56. top and TOPICS listed below (Basics, Files, File selection, etc.)
  57. Selecting a topic and pressing Enter brings up the second-level
  58. help screen with help TEXT. The very first line in the source file
  59. must be the TITLE. The TOPICS and their TEXT must be enclosed by
  60. #BEGIN and #END lines as follows:
  61.  
  62. ------------8<------------
  63. System screen
  64.  
  65. #Begin
  66. Basics
  67. Text which appears under Basics
  68. More text
  69. #End
  70.  
  71. #Begin
  72. Files
  73. Create files with 'New file'
  74.  
  75. Copy files with 'Copy file', but use
  76.  . . .
  77. #End
  78. ------------8<------------
  79.  
  80. A #BEGIN line must be immediately followed by TOPIC. All other
  81. lines, even blank ones, are counted as TEXT until #END is
  82. encountered. Anything between #END and next #BEGIN is ignored.
  83. TEXT must be at least one line long.
  84.  
  85. S3a Word processor does not let you type in many special symbols
  86. (like arrows, for example). However, you can embed any ASCII
  87. character in your help file by typing a '#' followed by a three-
  88. digit code (add leading zeroes if necessary). Examples:
  89.  
  90.           Format:             Appears in Help:
  91.           -------             ----------------
  92.           #065                A
  93.           #65                 #65
  94.           ##0978              #a8
  95.           #abc                #abc
  96.           #035END             #END
  97.           #035065             #065
  98.  
  99. You can use this in both TOPICS and TEXT.
  100.  
  101. You don't have to include the "About Help" topic. It will be added
  102. automatically at run-time. "Index" is currently unsupported.
  103.  
  104. Do NOT use word wrap while creating the source file. Add a CR to
  105. the end of every line. A line cannot be longer than the screen can
  106. allow. If you edit in Word, you can judge the width more
  107. accurately by making the Status window narrow, font proportional,
  108. size next to largest (like in Help). Remember to account for the
  109. fact that TOPICS will appear in bold and may be preceded by
  110. "Help:"
  111.  
  112. TEXT can have up to 128 lines. It will be scrolled if it does not
  113. fit vertically. The width of the help window is determined by the
  114. longest line in TEXT. It is a good idea to have more shorter lines
  115. than a few long ones, because a fair amount of memory can be saved
  116. by reducing the help window size (especially since it has a gray
  117. plane).
  118.  
  119. You can optionally specify the target path where HLP file should
  120. be created. If specified, it must appear on the second line, like
  121. this:
  122.  
  123.      Myapp
  124.      path=\app\myapp\
  125.  
  126.  
  127. Using SYS$HELP.OPO
  128. ==================
  129.  
  130. USAGE:
  131.  
  132.      ret% = HELP%:( ptr% )
  133.  
  134. PARAMETERS:
  135.  
  136.      ptr% points to a structure consisting of a string and two
  137. words. Declare it in your program as follows:
  138.  
  139.      LOCAL FNAME$(128), SCR%, POS% : REM order is important
  140.  
  141.      FNAME$         - full name of the help file, eg,
  142.                     A:\APP\MYAPP\MYAPP.HLP
  143.                     Your program is responsible for making sure
  144.                     that the file exists
  145.      
  146.      SCR%           - Initial help screen to display. If scr% is
  147.                     0, the first-level screen (topic list) is
  148.                     displayed. If scr% is greater than 0, the
  149.                     second-level screen (help text) is displayed
  150.                     and scr% is the topic number. You can use this
  151.                     parameter to create context-sensitive help.
  152.      
  153.      POS%           If pos% is 0, no help is displayed, but FNAME$
  154.                     is set to the current version of Help System
  155.                     as a string, eg, "2.0". If pos% is non-zero,
  156.                     help is displayed normally. The actual value
  157.                     is currently ignored.
  158.      
  159. RETURN VALUE:
  160.      
  161.      ret%<0         - Error code
  162.      ret%=$404      - Your program has received an Exit message
  163.                     while Help was active.
  164.  
  165. NOTES:
  166. - HELP%:() creates 2 windows so make sure you have 6 or less
  167. windows/bitmaps before calling it.
  168. - You can use LOCK ON/OFF before and after calling HELP%:() if you
  169. don't want the System to send an Exit message.
  170. - HELP%:() doesn't appear to contain any bugs, but no programmer
  171. can guarantee it.
  172. - You can run SYS$HELP.OPO as a program on its own, in which case
  173. you will be prompted to input the Help file name. Note that
  174. because its name starts with "SYS$", it will not show up on the
  175. system screen.
  176.  
  177. EXAMPLE PROCEDURE:
  178.  
  179. Here's a sample procedure that you can use to load help:
  180.  
  181. -----------------8<------------------
  182. PROC help:( topic% )
  183. local hname$(40), ptr%, ret%
  184. local fname$(128), scr%, opt% : rem Keep together
  185. fname$ = "m:\app\finder\finder.hlp" : scr% = topic% : opt% = 1
  186. if not fexist:( addr( fname$ ) )
  187.      giprint "Help not found"
  188.      return
  189. endif
  190. hname$ = "m:\opo\sys$help.opo"
  191. if fexist:( addr( hname$) )
  192.      trap loadm hname$
  193.      if err
  194.           giprint err$( ret% )
  195.           return
  196.      endif
  197. else
  198.      giprint "Help not installed"
  199.      return
  200. endif
  201. ret% = help%:( addr( fname$ ) )
  202. trap unloadm hname$
  203. if ret% < 0
  204.      giprint err$( ret% )
  205. elseif ret% = $404
  206.      stop
  207. endif
  208. ENDP
  209.  
  210. PROC fexist:( ptr% ) : rem Looks for a file on all local drives
  211. if exist( peek$( ptr% ) ) : return -1 : endif
  212. pokeb ptr% + 1, %a
  213. if exist( peek$( ptr% ) ) : return -1 : endif
  214. pokeb ptr% + 1, %b
  215. if exist( peek$( ptr% ) ) : return -1 : endif
  216. ENDP
  217. -----------------8<------------------
  218.  
  219.  
  220. HLP File Format
  221. ===============
  222.  
  223. HLP file is really an OPL database (ODB) file. Each record has two
  224. fields - 2-byte integer and string. The records can be of 3 types:
  225. TITLE, TOPIC and TEXT.
  226. TITLE record is the first record. It is followed by TOPIC records.
  227. Then come all TEXT records. The string field contains the text.
  228. The meaning of the associated integer depends on type of the
  229. record:
  230.  
  231. Type                          Integer i%
  232. ----                          ----------
  233. TITLE                         (i%/$200) - number of topics (128
  234.                               max)
  235.                               (i% and $1ff)