home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / turbopas / niceprnt.lbr / PP.DQC / PP.DOC
Text File  |  1986-06-21  |  7KB  |  176 lines
  1.  
  2.                                                                 PAGE 1
  3.  
  4.  
  5.  
  6.                   PP - Pascal Prettyprinting Program
  7.  
  8.                             14 March 1985
  9.  
  10.                                - Jon Hueras and
  11.                                  Henry Ledgard
  12.                                - Rick L. Marcus
  13.  
  14.  
  15. What PP Does
  16. ------------
  17.  
  18.      PP takes as input a Pascal program or program fragment and
  19. reformats it according to a standard set of prettyprinting rules.  The
  20. prettyprinted program is given as output.  PP makes no attempt to
  21. detect or correct syntactic errors in your program.  However,
  22. syntactic errors may result in erroneous prettyprinting.
  23.  
  24.      PP differs from some other prettyprinting programs in that it
  25. does not reformat your program "right down to every last semicolon."
  26. Such a philosophy requires formatting everything in a rigid fashion
  27. which is bound to be displeasing, or else it must provide you with a
  28. voluminous set of "options." Furthermore, such a scheme must do full
  29. syntax analysis of the program which means that it must be completely
  30. written and compilable.  If you wish to prettyprint a program still
  31. under development, then you are out of luck.
  32.  
  33.      PP, on the other hand, implements a strategy which states that it
  34. is not necessary to impose more than a "minimum" set of restrictions,
  35. and the prettyprinter should yield to your discretion beyond this
  36. minimum.  PP preserves blank lines and extra spaces you insert in the
  37. program as input, besides adding blank lines and extra spaces
  38. according to the rules for prettyprinting given below.
  39.  
  40.  
  41. General prettyprinting rules:
  42.  
  43.      1.  All statements and declarations begin on separate lines.
  44.  
  45.      2.  No input line may be longer than 80 characters.  Any output
  46.          line longer than 80 characters is continued on a separate
  47.          line.
  48.  
  49.      3.  The keywords "BEGIN", "END", "REPEAT", and "RECORD" are
  50.          forced to stand on lines by themselves (or possibly followed
  51.          by supporting comments).  In addition, the "UNTIL" clause of
  52.          "REPEAT-UNTIL" statement is forced to start on a new line.
  53.  
  54.      4.  A blank line is forced before the keywords "PROGRAM",
  55.          "PROCEDURE", "FUNCTION", "LABEL", "CONST", "TYPE", and "VAR".
  56.  
  57.      5.  A space is forced before and after the symbols ":=" and "=".
  58.          Additionally, a space is forced after the symbol ":".  Note
  59.          that only "="s in declarations are formatted; "="s in
  60.          expressions are ignored.
  61.  
  62. PP - Pascal Prettyprinting Program                              PAGE 2
  63.  
  64.  
  65.  
  66.  
  67.      6.  Spaces and blank lines already in your program are preserved
  68.          by PP, which adds (but does not subtract) blank lines and
  69.          spaces.  You can improve the readability of your programs by
  70.          taking advantage of this feature.  However, this feature also
  71.          means that you may sometimes have to manually de-indent (in
  72.          your editor) after block structure changes.
  73.  
  74.  
  75.  
  76. Indentation rules:
  77.  
  78.      1.  The body of a declaration is indented from the "LABEL",
  79.          "CONST", "TYPE", or "VAR" keyword which heads it.
  80.  
  81.      2.  The bodies of "BEGIN-END", "REPEAT-UNTIL", "WHILE", "WITH",
  82.          and "CASE" statements, as well as "RECORD-END" structures and
  83.          "CASE" variants (to one level) are indented from keywords
  84.          which head them.
  85.  
  86.      3.  An "IF-THEN-ELSE" statement is indented as follows:
  87.  
  88.                IF <expression>
  89.                   THEN <statement>
  90.                   ELSE <statement>
  91.  
  92.  
  93.  
  94. When to Use PP
  95. --------------
  96.  
  97.      PP is especially useful to reformat a Pascal program or program
  98. fragment that you have typed without regard to formatting (such as
  99. entering every line left-justified to save time).  Because the program
  100. need not be syntactically correct, PP provides the fastest means of
  101. obtaining a more readable version of your program.
  102.  
  103.      PP is best used to prettyprint a Pascal program already on a file
  104. or punched on cards.  PP changes neither the cards nor the file used
  105. as input.  Prettyprinting a program line-by-line as it is entered at a
  106. terminal is considerably less useful.
  107.  
  108.  
  109. How to Use PP
  110. -------------
  111.  
  112.      Type "PP" at the system command level followed by the old and new
  113. file names.  If the new file already exists, it will be overwritten
  114. without warning.  If the wrong number of file names are given, PP will
  115. print a message reminding the user of the correct system call.
  116.  
  117.  
  118.  
  119. PP - Pascal Prettyprinting Program                              PAGE 3
  120.  
  121.  
  122.  
  123. Examples
  124. --------
  125.  
  126.      1.  Reformat a program called "prog1.pas" under CP/M:
  127.  
  128.             PP prog1.pas prog1.new       ;  reformat a program
  129.             TYPE prog1.new               ;  check that it is correct
  130.             ERA prog1.pas                ;  delete the old version
  131.             REN prog1.pas=prog1.new      ;  rename the new version
  132.  
  133.      2.  Reformat the same program under MS-DOS:
  134.  
  135.             PP prog1.pas prog1.new
  136.             TYPE prog1.new
  137.             ERASE prog1.pas
  138.             RENAME prog1.new prog1.pas
  139.  
  140.      3.  Preview PP's output before writing to a file:
  141.  
  142.             PP prog.pas con:            ;  on CP/M
  143.             PP prog.pas con             ;  on MS-DOS
  144.  
  145.      4.  Remind oneself how to use PP:
  146.  
  147.             PP
  148.  
  149.  
  150. History
  151. -------
  152.  
  153.      PP prettyprints a Pascal program or program fragment given as
  154. input.  It was originally named PRETTYPRINT and was written in Pascal
  155. by Jon Hueras and Henry Ledgard, University Computing Center and
  156. Computer and Information Science Dept., University of Massachusetts at
  157. Amherst, in August, 1976.  (See "An Automatic Formatting Program for
  158. Pascal", by Jon Hueras and Henry Ledgard, Pascal Newsletter #6, page
  159. 70, November, 1976.)
  160.  
  161.      Small corrections were made to PRETTYPRINT by Charles Fischer,
  162. Dept.  of Computer Science, University of Wisconsin, Madison, in 1977.
  163. PRETTYPRINT was modified for CDC-6000 Pascal by Rick L.  Marcus,
  164. University Computer Center, University of Minnesota, in September,
  165. 1978, and was renamed PRETTY.  Marcus also wrote this documentation.
  166.  
  167.      Peter Grogono adapted PRETTYPRINT to CP/M, using Pascal/Z.  He
  168. also made several modifications and renamed it PP (date unknown).  In
  169. 1984 Willett Kempton adapted the Pascal/Z version to Turbo Pascal,
  170. which required only minor mods.  The Turbo version uses a portable
  171. argument library "ARGLIB.PAS" to get file names, which makes it easier
  172. to adapt PP to other Pascal systems.  The Turbo version has been
  173. tested under CP/M-80, CP/M-86, and MS-DOS.  Kempton also adapted this
  174. documentation, from the CDC version, to apply to the microcomputer
  175. version.
  176.