home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1995 November / PCWK1195.iso / inne / podstawy / dos / 4dos / 4uzytki / ez-btm11.exe / HELPTEXT.BTM < prev    next >
Text File  |  1994-03-30  |  5KB  |  137 lines
  1. :: [This line is left for writing the filename]
  2. set source=%@search[%0]
  3. :: %@filename[%source]  - This batch demonstrates how you can insert
  4. :: a short explanation text at the top of your batch file and have it
  5. :: displayed as a HELP text. This saves you from inserting a more or less
  6. :: duplicate text at some ":help" label in that batch file. Moreover, you
  7. :: can make use of my "master help procedure" (MASTHELP.BTM) as an external
  8. :: routine. The current batch indeed works that way. If you wish to test
  9. :: how this works via an internal routine, run batch with an "i" switch.
  10. :: ----------------------
  11. :: The idea is taken from a program in REXX. The procedure in 4DOS
  12. :: does not work as fast as it does in REXX, but you both gain elegance
  13. :: and save work, which is especially important if you often modify a
  14. :: program.
  15. :: ----------------------
  16. :: Syntax:
  17. :: %@name[%source] [filespecs]
  18. :: You can put here some further explanation
  19. :: Switches:
  20. :: (for example:) h, or ? -- This HELP
  21. :: (This is an example for describing switches / options)
  22.  
  23. :: NOTE:
  24. :: (1) the line
  25. :: set source=%@search[%0]
  26. :: must be inserted above the description text. Otherwise, the HELP
  27. :: procedure will not know from which file to read its lines.
  28. :: It is a precondition for this to work that your batch is located
  29. :: in a subdirectory defined in your PATH command.
  30.  
  31. :: (2) The description text MUST end with a blank line.
  32. :: If you prefer some other demarcation sign, you must edit the procedure
  33. :: accordingly.
  34.  
  35. :: For more details about the structure of this procedure and other
  36. :: options read below, and MASTHELP.BTM.
  37.  
  38. :: setlocal
  39. :: If you prefer your batch to execute its proper task rather than display
  40. :: a HELP text when run without arguments, activate the following (remove
  41. :: the double colons from the following and the "quit" line for these
  42. :: lines to work.)
  43.  
  44. :: if %@index[%&,h] eq 0 .or. %@index[%&,?] eq 0 goto help
  45. :: (The actual batch file comes here)
  46. :: quit
  47.  
  48. :internal
  49. :: I've added this to allow the internal routine to work.
  50. iff "%1"=="i" then
  51. setlocal
  52. goto help_2
  53. endiff
  54.  
  55. :: ----sub-routines--------
  56. :help
  57. :: The EXTERNAL routine MASTHELP.BTM is called from this section.
  58. :: See below how you can have it as an INTERNAL routine.
  59. :: set lnumber=x
  60. :: ==>remove '::' and put a number instead of 'x' if you wish
  61. ::    the HELP text to begin with some other line than the 3rd line.
  62. ::    (The 3rd line is the default of this procedure. It is defined
  63. ::    in the external procedure MASTEHELP.BTM. Remember that the first
  64. ::    line in 4DOS is "0".)
  65. iff exist %@search[masthelp] then
  66.     call masthelp
  67.     cancel
  68. else
  69.     cls^screen 3 0
  70.     screen %@eval[%_row+1] 4 You must have %@upper[masthelp.btm]
  71.     screen %@eval[%_row+1] 4 for this HELP procedure to work
  72.     echo.
  73.     quit
  74. endiff
  75.  
  76. :: ---- Making the external HELP procedure an internal procedure ---
  77. :: =================================================================
  78. :: NOTE: The external procedure can be inserted as an internal procedure
  79. :: at the ":help" label. If you prefer that, here's how it can look
  80. :: (with detailed line-by-line explanation below).
  81.  
  82. :help_2
  83. cls^screen 2 0
  84. :: ==>Change number below if you wish the HELP text to begin
  85. ::    at some other line than the 3rd line. (Remember that the first line
  86. ::    in 4DOS is "0".)
  87. set num=2
  88.     do forever
  89.        set hl=%@instr[3,70,%@line[%source,%num]]
  90.        set num=%@eval[%num+1]
  91.      if "%hl"=="" leave
  92.        screen %@eval[%_row+1] 4 %hl
  93.     enddo
  94. endlocal
  95. echo.
  96. quit
  97.  
  98. :: ----a line-by-line-explanation of the above procedure---
  99. cls^screen 2 0
  100.   :: this clears the screen and puts the cursor on row #2
  101. set num=2
  102.   :: this sets a counter for "2", which means that you wish to
  103.   :: start reading the lines from the file from the THIRD line.
  104. do forever
  105.   :: this means that the loop will go on as long as it is not told
  106.   :: explicitly to stop. This option is available only in 4DOS 5.x.
  107.   :: For prior versions the loop must be written a bit differently.
  108. set hl=%@instr[3,70,%@line[%source,%num]]
  109.   :: save line number 1 (2,3,4,...) from the batch file on the variable
  110.   :: "hl", then extract from each line of the description text only the
  111.   :: part that begins on position 4 [first position is 0 in 4DOS].
  112.   :: Note: This can be written in two different lines: one line for
  113.   :: saving the relevant line:
  114.   :: set hl=%@line[%source,%num]
  115.   :: then one line for extracting the desired section:
  116.   :: set hl=%@instr[3,70,%hl]
  117.   :: I preferred using one line for both procedures for the sake of
  118.   :: brevity; but sometimes readability is more important.
  119.   :: Note_2: Note that @instr[] and not @substr[] is used, since
  120.   :: @subsrt[] has problems with commas in lines (RFM for details.)
  121. set num=%@eval[%num+1]
  122.   :: increment now the counter by 1
  123. if "%hl"=="" leave
  124.   :: if the line was empty, stop the loop (and go to the lines after
  125.   :: "enddo")
  126. screen %@eval[%_row+1] 4 %hl
  127.   :: put the relevant line one row below the current row on the 4th
  128.   :: column.
  129. enddo
  130.   :: end / go back to beginning of loop)
  131. endlocal
  132.   :: erase the temporary variables set in this file from the environment.
  133. echo.
  134.   :: add one blank line to the text displayed on screen.
  135. quit
  136.  
  137.