home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / ibm1 / do101j2.arj / DOCUMENT.SCR < prev    next >
Encoding:
Text File  |  1991-12-19  |  5.0 KB  |  122 lines
  1. /GOSUB Heading
  2.     This command allows you to setup your »%t«DO»#« script as a
  3.     document.  It is especially handy for automated
  4.     documentation.  With »ye«DocumentMode»#« set »re«ON»#«, the labels in your
  5.     script act like chapters in a book.  The script will process
  6.     as long as you are in the same "chapter" and will terminate
  7.     processing when you reach a new chapter.
  8.  
  9.     Once the "chapter" has been processed, the script returns to
  10.     the special label "»ye«TOC»#«" (for »cy«Table of Contents»#«).  The "»ye«TOC»#«"
  11.     section is used to select a new "chapter" to read.
  12.  
  13.     The chapter being processed must be stored in the special
  14.     variable "»ma«CHAPTER»#«".  This will be used by the system to
  15.     determine when a section is completed.
  16.  
  17.     Document mode is reset to »re«FALSE»#« each time you »%t«Exec»#« a script
  18.     or enter »ye«Interactive mode»#« ("»%t«/INTERACTIVE»#«"). The status is
  19.     reset when the »%t«Exec»#«'ed script returns ("»%t«/ENDEXEC»#«") or you
  20.     exit Interactive mode ("»%t«/EXIT»#«").
  21.  
  22.     Even though document mode is reset each time you exit a
  23.     script, it is good programming practice, however to set
  24.     document mode »re«OFF»#« when you exit a script.
  25.  
  26.     The following is a simplified »%t«/DOCUMENT»#« script.  It
  27.     has been written in two columns so you can see it on the same
  28.     page.
  29.  
  30. .pg wi full clr
  31.     /DOCUMENT ON                    │   :1
  32.     :TOC                            │       {Body of chapter 1}
  33.         Select Chapter:             │   :1.1
  34.                                     │       {Body of section 1}
  35.         1.  Chapter 1               │   :1.2
  36.             1.1  Section 1          │       {Body of section 2}
  37.             1.2  Section 2          │   :2
  38.         2.  Chapter 2               │       {Body of chapter 2}
  39.             2.1  Section 1          │   :2.1
  40.             2.2  Section 2          │       {Body of section 1}
  41.         0.  Exit                    │   :2.2
  42.     /SET Def 0                      │       {Body of section 2}
  43.     /ASK CHAPTER Def "Chapter:"     │   :0
  44.                                     │   /DOCUMENT OFF
  45.                                     │   * END of SCRIPT
  46.   ──────────────────────────────────┴─────────────────────────────────────────
  47. .reset go 1 1
  48.     »bo«/DOCUMENT ON»#«                    │   :1
  49. /GOSUB SetWindow
  50.   The »%t«/DOCUMENT»#« command sets the document mode on.  Then the script
  51.   drops into the table of contents section.
  52. .pg wi full go 1 1
  53.     /DOCUMENT ON                    │   :1
  54. .go 1 13
  55.     /ASK »bo«CHAPTER»#« Def "Chapter:"     │   :0
  56. /GOSUB SetWindow
  57.   Note the use of the special variable »ye«CHAPTER»#«.  This will be
  58.   used by the system to determine when the section is complete.
  59. .pg clr
  60.   Labels in the sections must take a form that has the »ye«CHAPTER»#«
  61.   followed by sub-chapters: »gr«{chapter}{subchapter}{section}...»#«
  62.  
  63.   »%t«DO»#« will continue to process sections until it finds a label
  64.   which does not fit the pattern in the »ye«CHAPTER»#« variable.
  65. .pg wi full go 1 1
  66.     /DOCUMENT ON                    │   »bo«:1»#«
  67.     :TOC                            │       {Body of chapter 1}
  68.         Select Chapter:             │   »bo«:1.1»#«
  69.                                     │       {Body of section 1}
  70.         1.  Chapter 1               │   »bo«:1.2»#«
  71.             1.1  Section 1          │       {Body of section 2}
  72.             1.2  Section 2          │   »+re«:2»#«
  73. .go 1 13
  74.     /ASK CHAPTER Def "Chapter:"     │   :0
  75. /GOSUB SetWindow
  76.   For example, if you entered "»ye«1»#«" in response to the »%t«/ASK»#« prompt,
  77.   »%t«DO»#« would process sections "»gr«:1»#«","»gr«:1.1»#«","»gr«:1.2»#«", but would stop
  78.   at label "»re«:2»#«" since it does not match the pattern of having "»ye«1»#«"
  79.   at the start of the label.
  80. .pg wi full
  81.     /DOCUMENT ON                    │   :1
  82.     :TOC                            │       {Body of chapter 1}
  83.         Select Chapter:             │   :1.1
  84.                                     │       {Body of section 1}
  85.         1.  Chapter 1               │   :1.2
  86.             1.1  Section 1          │       {Body of section 2}
  87.             1.2  Section 2          │   :2
  88. /GOSUB SetWindow
  89. .clr
  90.   »gr«NOTE»cy«: »%t«DocumentMode»#« can be turned »ma«OFF»#« in a document section to
  91.         process »%t«DO»#« commands which rely on labels and then turned
  92.         »ma«ON»#« again to continue to process the remainder of the
  93.         script as a document.
  94. .pg clr
  95.   Now, we'll execute »ye«TESTDOC.SCR»#« which implements this basic script
  96.   so you can see the workings of the »%t«/DOCUMENT»#« command.
  97.  
  98. /PAGEPROMPT "Press <enter> to start TESTDOC.SCR"
  99. .pg wi full
  100. /PAGEPROMPT
  101. /TESTDOC
  102. /GOSUB Heading
  103.   As you have seen, »%t«DocumentMode»#« provides important features
  104.   when using »%t«DO»#« to implement on-line documentation.
  105.  
  106. /GOTO END
  107. :SetWindow
  108. .wi 1 17 80 25 clr
  109. /RETURN
  110. :Heading
  111. .pg wi full clr cy
  112.     COMMAND NAME»gray«: »%t« SetDocumentMode »ye«
  113.  
  114.     /DOCUMENT {ON|OFF}
  115. /cw
  116. /RETURN
  117. :END
  118. /ENDEXEC
  119.  
  120.  
  121.  
  122.