home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / turbopas / t_ref.arc / T-REFCH2.DOC < prev    next >
Text File  |  1987-01-15  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4.                       Chapter II - The Source Lister
  5.  
  6.      This  chapter  deals primarily with the Source Listing  program:  how  to
  7. print  the information you want and how to interpret the listing.  The  Source
  8. Listing  program  is  activated  by positioning the cursor  over  the  'Source
  9. Listing' field,  and striking the space bar until the word "ON" appears within
  10. the cursor.   To deactivate the source lister, hit the space bar again and the
  11. word "OFF" will appear.   The nine fields that appear on the screen below  the
  12. 'Source  Listing'  field relate to specific information to be included or  not
  13. included  in the source listing.   They are all updated in the same manner  as
  14. the  'Source  Listing' field:  by placing the block cursor over the field  and
  15. striking  the  space  bar until the desired value appears  within  the  cursor
  16. block.  The fields are as follows:
  17.  
  18.      The  'Reserve  Words' field is used to tell the program how  the  reserve
  19. words  are  to  be  formatted to the output.   You can  specify  one  of  four
  20. different formats: "UPPER" capitalizes all letters, "LOWER" prints all letters
  21. in lower-case,  "FORML" follows formal naming conventions,  and "AS IS" prints
  22. the letters as they are read.  The following are examples of different reserve
  23. words  and  how the output would be formatted;  the first column  is  how  the
  24. reserve word would be hypothetically read from the input file:
  25.  
  26.        Input          UPPER          LOWER          FORML          AS IS
  27.        -----          -----          -----          -----          -----
  28.        begin          BEGIN          begin          Begin          begin
  29.         FOR            FOR            for            For            FOR
  30.        wITH           WITH           with           With           wITH
  31.        Array          ARRAY          array          Array          Array
  32.  
  33.      The  'Identifiers'  field's  function is similar to the  'Reserve  Words'
  34. field described above:  it formats the style of lettering for all  identifiers
  35. to that requested.  The same four formatting styles listed above are available
  36. for  this  field.   However,  here we must describe a feature of  the  "FORML"
  37. format not mentioned above.   Since most Pascal compilers allow the use of the
  38. underline  symbol (_) within an identifier (to make the source code more read-
  39. able),  the "FORML" style makes use of this:  not only is the first letter  in
  40. the identifier capitalized,  but each letter following the underline symbol is
  41. also  capitalized.   Therefore,  'hot_item' becomes 'Hot_Item',  'not_so_fast'
  42. becomes 'Not_So_Fast', and 'ab_ra_ca_da_bra' becomes 'Ab_Ra_Ca_Da_Bra'.
  43.      The  purpose  of  having four formats is to provide a  large  variety  of
  44. choices.  Even given these variations, you will most likely select and use one
  45. format  for reserve words (i.e.,  "UPPER") and another format for  identifiers
  46. (i.e.,  "FORML")  that best suits your specific purposes.
  47.  
  48.      The  'Line  Numbers' field activates ("ON") or  deactivates  ("OFF")  the
  49. printing  of  source  line numbers to the left of each  line  of  output.   If
  50. activated,  each  source  line on the output will have a line  number  printed
  51. ahead of it.   There are two formats the line numbers may appear in, depending
  52. on  whether  the  'Include Files' field is activated during the  listing  (see
  53. page 10 for a description of this field).
  54.      If  the 'Include Files' field is activated,  the line numbers will appear
  55. in two columns:  the line number of the main input file and the line number of
  56. the include file.   The line number of the main input file is incremented  for
  57. each  line  read from the 'Active Input File' as specified at the top  of  the
  58. screen.  When an include file compiler directive, such as '{$i extra.prc}', is
  59.  
  60.  
  61.                                 6
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. scanned from the main input file,  the program will begin printing the include
  71. file  source  code starting immediately after printing the line in  which  the
  72. include  file compiler directive is on.   At this point (until the end of  the
  73. include file is reached),  the line number of the main input file will  remain
  74. the  same and the line number of the include file will begin (starting from 1)
  75. incrementing.   The  line  number of the include file,  when  the  program  is
  76. reading from the main input file,  is not printed.  For example, the following
  77. shows  how,  when the compiler directive '{$I this.prc}' is scanned,  the file
  78. 'THIS.PRC' is sent directly to the output.
  79.  
  80.    1       PROGRAM Sample;
  81.    2         VAR I:Integer;
  82.    3
  83.    4         {$I This.Prc}
  84.    4    1    PROCEDURE This;
  85.    4    2      BEGIN
  86.    4    3        Write('This is just a sample.');
  87.    4    4      END;
  88.    5
  89.    6         BEGIN
  90.    7           FOR I:=1 to 10 DO This;
  91.    8           Writeln;
  92.    9         END.
  93.  
  94.      The  use of separate line numbers on the listing becomes evident when you
  95. bring  either  the main file or any of the include files up  under  the  Turbo
  96. editor.   Since the Turbo  editor prints the cursor's location on the top line
  97. of  the screen,  the line number you are searching for is the same line number
  98. on  the listing.  If the 'Include Files' field is not activated (e.g.,  "No"),
  99. only the line number of the main input file is printed.   For example,  if the
  100. above main file were printed without the include file activated (set to "No"),
  101. it would look like:
  102.  
  103.    1 PROGRAM Sample;
  104.    2   VAR I:Integer;
  105.    3
  106.    4   {$I This.Prc}
  107.    5
  108.    6   BEGIN
  109.    7     FOR I:=1 to 10 DO This;
  110.    8     Writeln;
  111.    9   END.
  112.  
  113.      The 'Lexical Levels' field,  when activated ("ON"),  will print for  each
  114. source  line  a value representing the lexical,  or procedural,  depth of  the
  115. program.   Therefore,  as  the program scans the beginning of a  procedure  or
  116. function, the lexical level of the program is incremented; the level is decre-
  117. mented when the procedure or function is exited.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                 7
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.    1  PROGRAM Sample;
  137.    1    VAR I:Integer;
  138.    1
  139.    2    PROCEDURE This;
  140.    2
  141.    3      PROCEDURE Now_That;
  142.    3        BEGIN
  143.    3          Writeln;
  144.    3        END;
  145.    2
  146.    2      BEGIN
  147.    2        Write('This is just a sample.');
  148.    2        Now_That;
  149.    2      END;
  150.    1
  151.    1    BEGIN
  152.    1      FOR I:=1 to 10 DO This;
  153.    1    END.
  154.  
  155.      The  'Block  Levels' field,  when activated ("ON"),  will print  a  value
  156. representing  the structured statement depth within the procedure or  function
  157. being scanned.   The value is printed on each line of the output.   Whenever a
  158. structured statement (e.g.,  the IF,  the FOR, the REPEAT, the CASE, the WITH,
  159. the WHILE,  or the compound BEGIN-END statement) is entered during the scan of
  160. the  source  code,  the block depth of the procedure is  incremented,  and  is
  161. decremented upon exiting the structured statement.
  162.  
  163.    0  PROGRAM Sample;
  164.    0    VAR I:Integer;
  165.    0
  166.    0    PROCEDURE This;
  167.    1      BEGIN
  168.    1        Write('This is just a sample.');
  169.    1      END;
  170.    0
  171.    1    BEGIN
  172.    2      FOR I:=1 to 10 DO
  173.    2        This;
  174.    1      Writeln;
  175.    1    END.
  176.  
  177.      The 'Active Procedures' field, when activated ("ON"), will print the name
  178. of  the  procedure or function (presently being scanned) to the right  of  the
  179. output source code.  The name is enclosed in brackets (between '{' and '}') to
  180. increase  the documentation effects of the source and to make it  possible  to
  181. recompile the output source.
  182.  
  183.      The  following  is an example of the program's output if this  field  was
  184. activated.  (This  is also an excellent way to recognize new lines in  version
  185. updates  to source files.   Those lines added after a version is complete  and
  186. updated by T-Ref would not have this field at the end of the lines.)
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                8
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PROGRAM Sample;                                        { SAMPLE }
  203.   VAR I:Integer;                                       { SAMPLE }
  204.                                                        { SAMPLE }
  205.   PROCEDURE This;                                      { THIS }
  206.     BEGIN                                              { THIS }
  207.       Write('This is just a sample.');                 { THIS }
  208.     END;                                               { THIS }
  209.                                                        { SAMPLE }
  210.   BEGIN                                                { SAMPLE }
  211.     FOR I:=1 to 10 DO This;                            { SAMPLE }
  212.     Writeln;                                           { SAMPLE }
  213.   END.                                                 { SAMPLE }
  214.  
  215.  
  216.      Any  of  the listable information described above may be combined in  any
  217. combination.  Since the 'Line Numbers' field,  the 'Lexical Levels' field, and
  218. the 'Block Levels' field are printed to the left of the source for each  line,
  219. a  combination of more than one of these will create a column for each one  in
  220. that  specific order.   For example,  if all three fields are  activated,  the
  221. output would be as follows:
  222.  
  223.    1        1   0  PROGRAM Sample;
  224.    2        1   0    VAR I:Integer;
  225.    3        1   0
  226.    4        1   0    {$I This.Prc}
  227.    4    1   2   0    PROCEDURE This;
  228.    4    2   2   0
  229.    4    3   3   0      PROCEDURE Now_That;
  230.    4    4   3   1        BEGIN
  231.    4    5   3   1          Writeln;
  232.    4    6   3   1        END;
  233.    4    7   2   0
  234.    4    8   2   1      BEGIN
  235.    4    9   2   1        Write('This is just a sample.');
  236.    4   10   2   1        Now_That;
  237.    4   11   2   1      END;
  238.    5        1   0
  239.    6        1   1    BEGIN
  240.    7        1   2      FOR I:=1 to 10 DO This;
  241.    8        1   1    END.
  242.  
  243.      The  'Header' field is used to activate ("ON") the inclusion of a  header
  244. to  be  printed at the top of each page of source output.   The header can  be
  245. from two to five lines and each line can be up to 75 columns in  length.   The
  246. F3 function key creates the header to be printed.  If a header is printed, the
  247. program  will automatically buffer 3 blank lines before the header (the  first
  248. line of the new page) and 2 blank lines after the header (before the next line
  249. of source code),  so it is not necessary to buffer the header with blank lines
  250. within the header itself.
  251.  
  252.      The  'Page Numbering' field will,  when activated  ("ON"),  automatically
  253. number the pages of the output source (whether it is going to a file or to the
  254. printer).  A  date/time tag is printed on the page  number  line,  also.   The
  255. number of lines per page is set by the F6 function key.   If page numbering is
  256. deactivated  ("OFF") and the output is going to a file,  the source is contin-
  257.  
  258.  
  259.                                 9
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. uous with no blank lines between pages.   If page numbering is deactivated and
  269. the  output is to the printer,  the listing will automatically  include  three
  270. blank lines at the end of each page and one blank line at the head.
  271.  
  272.      NOTE: When both the 'Header' and 'Page Numbering' fields are turned "Off"
  273. and  the output is routed to a specified file (the 'Active Output File'  field
  274. is  not blank),  paging,  that is blank lines between pages,  will not  occur.
  275. Therefore, the output source is continuous.  If either or both of these fields
  276. are "On", paging will occur; whether output is to the printer or to a file.
  277.  
  278.      NOTE:  There  are separate switches on headers and page numbering for the
  279. source  lister and the cross referencer.   This feature was provided to  allow
  280. more  flexible  customized listing when run separately.   When both  a  source
  281. listing and cross reference listing are desired, we recommend you set these to
  282. the same values.  Since it is difficult to accurately assess all combinations.
  283. Therefore,  the  output characteristics may differ from the desired results of
  284. the listing if the above stated recommendation is not adhered to.
  285.  
  286.      The  'Include  File' field informs the program whether or  not  to  print
  287. external  files  (normally  included in compilation through  an  include  file
  288. compiler  directive (i.e.,  '{$I THIS.PRC}')) directly in with the main source
  289. code.  When activated ("YES"), include files are automatically placed into the
  290. output's  source listing immediately after the include file compiler directive
  291. is  interpreted.   There  is additionally an OPTIONAL  setting  ("OPT")  which
  292. allows you to selectively decide which include files are to be printed.   When
  293. this  setting  is used,  a message is sent to the message area of  the  screen
  294. every  time an include file compiler directive is scanned,  asking for  deter-
  295. mination  as  to  whether the file is to be included in  the  source  listing.
  296. Responding  "Y"es will route the include file source to the output;  "N"o will
  297. cause the include file source listing to be skipped.
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                10
  326.  
  327.  
  328.  
  329.  
  330.  
  331.