home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / skeleton.zip / TellHelp.cmd < prev   
OS/2 REXX Batch file  |  1995-08-03  |  12KB  |  256 lines
  1. /*****************************************************************************\
  2. | Display embedded help information from certain .cmd files.                  |
  3. |                                                                             |
  4. | $Revision:   1.0  $
  5. |     $Date:   03 Aug 1995 20:11:28  $                                         |
  6. | Libraries:   REXXSAA, REXXUTIL, [REXXLIB]                                   |
  7. |  Category:   Utility                                                        |
  8. |     Class:   Programming                                                    |
  9. |      Type:   User Help                                                      |
  10. |    Author:   Bob Rice - CompuServe: 72421,3016                              |
  11. |                                                                             |
  12. | Copyright (c) 1995 Empirical Heuristics                                     |
  13. \**************************************************************************r4*/
  14. /*  !tr! = value('TRACE',,'OS2ENVIRONMENT'); parse source . . !who!          */
  15. /*  if !tr! \= '' then say '--> Entering' !who!; trace value !tr!; nop       */
  16.  
  17.   parse arg helptype, pgmfile, pgm_ver, pgm_date, prolog_ver
  18.   if wordpos(translate(helptype),'/? /H /HELP -H -HELP') > 0 then helptype = '?'
  19.   if helptype   = '' then helptype = '?'
  20.   if pgmfile    = '' then parse source . . pgmfile
  21.   if pgm_ver    = '' then pgm_ver    = 'Unknown Version'
  22.   if pgm_date   = '' then pgm_date   = 'Unknown Date'
  23.   if prolog_ver = '' then prolog_ver = '<none>'
  24.  
  25.   drive = filespec('D',pgmfile)
  26.   path  = filespec('P',pgmfile)
  27.   parse value filespec('N',pgmfile) with pgmname '.' .
  28.   absfile = drive || path || pgmname'.abs'
  29.   parse value SysTextScreenSize() with rows .   /* Number of screen rows     */
  30.   rows = rows - 2                               /* Usable rows               */
  31.  
  32.   /*-------------------------------------*\
  33.   | Read in the file containing the help. |
  34.   \*-------------------------------------*/
  35.   if RXFUNCQUERY('fileread') = 0 then           /* Use RexxLib function      */
  36.     call fileread pgmfile, 'line.',, 'E','CRANDLF'
  37.   else do                                       /* Use slower REXXSAA func   */
  38.     i = 0
  39.     do while lines(pgmfile) > 0
  40.       i = i + 1
  41.       line.i = linein(pgmfile)
  42.     end
  43.     line.0 = i
  44.     call stream pgmfile, 'C', 'CLOSE'
  45.   end
  46.  
  47.   ?flg  = 0                                     /* Stop at Syntax: or Params:*/
  48.   ??flg = 0                                     /* Stop at Tech Info         */
  49.   /*------------------------------------------*\
  50.   | Extract info from header box and scan past |
  51.   | the program up to where the help begins.   |
  52.   \*------------------------------------------*/
  53.   do i = 1 to line.0
  54.     if pos(left(line.i, 1), '/|\*') > 0 then do
  55.       select
  56.         when pos('Revision:', line.i) > 0 then do
  57.           parse var line.i 'Revision:' pgm_ver '$'
  58.           pgm_ver = strip(pgm_ver)
  59.         end
  60.         when pos('Date:', line.i) > 0 then do
  61.           parse var line.i 'Date:' d m y .
  62.           pgm_date = d m y
  63.         end
  64.       otherwise nop
  65.       end
  66.     end
  67.     if left(line.i, 16) \= '/*--Begin Help--' then iterate
  68.     leave
  69.   end
  70.   /*------------------------------------------*\
  71.   | Write and display some header information. |
  72.   \*------------------------------------------*/
  73.   if helptype = '????' then do
  74.     call SysFileDelete absfile
  75.     call lineout absfile, pgmfile '--' pgm_ver '--' pgm_date
  76.     call lineout absfile, ''
  77.   end
  78.   say pgmfile
  79.   j = 1
  80.   if prolog_ver \= '<none>' then do
  81.     say ' Prolog version:' prolog_ver
  82.     j = j + 1
  83.   end
  84.   say 'Program version:' pgm_ver '--' pgm_date
  85.   say
  86.   j = j + 2                                     /* Output line counter       */
  87.   /*-----------------------------*\
  88.   | Display the help information. |
  89.   \*-----------------------------*/
  90.   do i = i + 1 to line.0
  91.     if left(line.i, 12) = '--End Help--' then leave
  92.     if wordpos('Syntax:', line.i) = 1 |,
  93.        wordpos('Params:', line.i) = 1 then ?flg = 1
  94.     if ?flg & helptype = '?' & line.i = '' then leave
  95.     if wordpos('Technical Notes', line.i) = 1 then ??flg = 1
  96.     if ??flg & helptype = '??' then leave
  97.     if helptype = '????' then call lineout absfile, line.i
  98.     else do
  99.       say line.i
  100.       j = j + 1
  101.       if j // rows = 0 then do
  102.         ans = AskUser('Cq','Continue or quit?')
  103.         if ans = 'Q' then exit
  104.       end
  105.     end
  106.   end
  107.   /*----------------------------------*\
  108.   | Write some trailer information or  |
  109.   | scroll screen up for nice display. |
  110.   \*----------------------------------*/
  111.   if helptype = '????' then do
  112.     call lineout absfile, ''
  113.     call lineout absfile, '(Prolog version:' prolog_ver')'
  114.     call stream  absfile, 'C', 'CLOSE'
  115.     say 'Help abstract put in file' absfile'.'
  116.   end
  117.   else do                                      /* Scroll screen up          */
  118.     if j < rows - 2 & helptype = '?' then do
  119.       say
  120.       say 'Note: A parameter of ?? will display additional help.'
  121.       j = j + 2
  122.     end
  123.     do while j // rows <> 0
  124.       say
  125.       j = j + 1
  126.     end
  127.   end
  128.   exit
  129. /*--Begin Help-----------------------------------------------------------------
  130. From a .cmd file, display all or part of the embedded help information between
  131. the Begin Help marker line and the End Help marker line.  If available, the
  132. program version and date are extracted from the .cmd file header box.  In
  133. addition, if the .cmd file employs the standard REXX Skeleton, the prolog
  134. version is also included in the information displayed.  All this information
  135. may optionally be placed in an abstract file.  See the Technical Notes for
  136. additional information.
  137.  
  138. Params: [help-type [, pgm-fspec, [, pgm-ver [, pgm-date [, prolog-ver] ] ] ] ]
  139.  
  140. where:
  141.  
  142.   help-type     specifies how much help you want to see or what to do with it.
  143.                 This parameter can be one of the following:
  144.  
  145.                   [ ?  | /?  | /h | /help | -h | -help ]    displays from the
  146.                         beginning of the embedded help up to the first blank
  147.                         line after a line starting, not necessarily in column
  148.                         1, with either of the strings "Syntax:" or "Params:".
  149.                         The case of these two strings is important, but the
  150.                         case of the parameter itself is not.  If neither of
  151.                         these strings is found, all the help is displayed.
  152.                         This is the value assumed if none is given.
  153.  
  154.                   ??    displays from the beginning of the embedded help up to,
  155.                         but not including, a line starting, not necessarily in
  156.                         column 1, with the string "Technical Notes", such a
  157.                         line is available.  Case is important.  If this string
  158.                         is not found, all the help is displayed.
  159.  
  160.                   ???   displays from the beginning of the embedded help up to,
  161.                         but not including, the End Help marker line.  Case is
  162.                         important.  If the End Help marker line is not found,
  163.                         all remaining lines will be displayed.
  164.  
  165.                   ????  performs like ??? but the help information is placed
  166.                         in an abstract file instead of being displayed on the
  167.                         screen.  The name of the file is extracted from
  168.                         pgm-fspec and a file extent of .ABS is used.
  169.  
  170.   pgm-fspec     is the filespec of the program file for which you want the help
  171.                 extracted.  If this parameter is not specified, then this
  172.                 program is assumed.
  173.  
  174.   pgm-ver       is the version number of the program specified in the pgm-fspec
  175.                 parameter.  If this parameter is not specified, then 'Unknown
  176.                 Version' is used.
  177.  
  178.   pgm-date      is the date of the program specified in the pgm-fspec
  179.                 parameter.  If this parameter is not specified, then
  180.                 'Unknown Date' is used.
  181.  
  182.   prolog-ver    is the version number of the skeletal prolog in the program
  183.                 named in the pgm-spec parameter.  If this parameter is not
  184.                 specified, then '<none>' is used.
  185.  
  186. Note:  For "ordinary" use, the above three parameters should not be used.
  187. Although you may choose to use them, they are provided for the use of the
  188. prolog in the standard REXX Skeleton.  The definition and specifications for
  189. these three parameters may change in future releases.
  190.  
  191. ________________
  192. Alternate Params: [ ? | ?? | ??? | ???? ]
  193.  
  194. where:
  195.  
  196.   ?     Displays up to the "Syntax:" or "Params:" portion of this help text.
  197.  
  198.   ??    Displays this entire help text except for the technical information.
  199.  
  200.   ???   Displays this entire help text.
  201.  
  202.   ????  Puts this help text into a file whose name is the same as the name of
  203.         this program and whose extent is .ABS.  The file is written to the same
  204.         directory as that in which this program resides.
  205.  
  206. _______________
  207. Technical Notes
  208.  
  209. This program is intended to be used as both a general utility and as part of
  210. the standard REXX Skeleton.
  211.  
  212. The Begin Help marker line is a line beginning in column 1 with the REXX open
  213. comment delimiter pair (slash asterisk) followed by the string "--Begin Help--"
  214. in columns 3 through 16.  The End Help marker line is a line containing the
  215. string "--End Help--" in columns 1 through 12 and followed somewhere on the
  216. same line by the REXX close comment delimiter pair (asterisk slash).
  217.  
  218. The header box is considered to be all lines, starting from line 1 of the file,
  219. which have one of the four characters /, |, \, or * in column 1 of the line.
  220. Within the header box are several field labels, of which the Revision: and
  221. Date: are of immediate interest.  This program searches for these strings in
  222. the header box to determine the program version and date, respectively.  The
  223. program version is considered to be anything following the Revision: label.
  224. The date must be of the form dd Mmm yyyy.  The first three tokens following the
  225. Date: label are considered to be the date.  See the header box in this file as
  226. an example.  (The dollar signs in this particular example are there for
  227. compatibility with my version control system and may be eliminated if desired.
  228. The additional labels shown in this header box are not used by this help
  229. extraction program, but are there for the use of a possible follow-on program
  230. to catalog .cmd files.)
  231.  
  232. If you wish to utilize the abilities of this program to display embedded help
  233. text from your own code, here are some suggested code fragments to use at the
  234. beginning of your program.  Use the following if it is valid to call your
  235. program with no parameters:
  236.  
  237.   if left(arg(1),1) = '?' then do
  238.     parse source . . !pgm!; call TellHelp arg(1), !pgm!; exit 2; end
  239.  
  240. If your program requires at least one parameter, use the following:
  241.  
  242.   if arg(1) = '' | left(arg(1),1) = '?' then do
  243.     parse source . . !pgm!; call TellHelp arg(1), !pgm!; exit 2; end
  244.  
  245. Note that this program will run a bit faster if REXXLIB has been loaded and
  246. registered, although REXXLIB is not a requirement.
  247.  
  248. ___________________
  249. Development History
  250.  
  251. $Log:   Q:/rxdv/skeleton/vcs/tellhelp.cm!  $
  252.   
  253.      Rev 1.0   03 Aug 1995 20:11:28
  254.   Initial revision.
  255. --End Help-------------------------------------------------------------------*/
  256.