home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / pascal-p / pp319doc.lbr / FILTERS.MZN / FILTERS.MAN
Encoding:
Text File  |  1987-02-03  |  7.6 KB  |  157 lines

  1. .macro chttl = FILTERS#and#CONVENTIONS
  2. .ch .chttl
  3. .hl 1 General
  4. Various  "filter" programs are provided.   These have the  common
  5. characteristic that they use only "input" and "output" files, and
  6. perform  some sort of translation of the input file.  "Input" and
  7. "output" are always textfiles.   Filters have no extraneous files
  8. over which to prompt the user, and no added verbiage is generally
  9. desired on the output, thus they are unable to prompt the user.
  10.  
  11. The  programs are generally executed by using the i/o redirection
  12. facilities ">" and "_<" (goes__to and comes__from respectively). .bb
  13. A minor  exception  is .eb
  14. "TYPETEXT",  as detailed below.  COPYCOLS also provides for
  15. additional parameters in the command line.
  16.  
  17. .hl 1 LINE TERMINATORS
  18.  
  19. CPM  textfiles  universally use the convention  that  lines  are
  20. terminated by a _<cr>_<lf> pair.   Some systems generate files that
  21. omit  the _<lf>.   Any such files are legible to Pascal  programs,
  22. and  after  passing through these filters will have  the 
  23. conventional line terminators inserted.
  24.  
  25. .note WARNING:
  26. The ISO and ANSI Pascal standards specify, and for good
  27. reason,  that  an EOF must immediately follow an EOLN in  a  
  28. non-empty textfile,  i.e.  all lines must be terminated by EOLN
  29. (normally  a _<ret> under CPM).   Files created by other systems  may
  30. not respect this.  WordStar is a notable offender, where the user
  31. must  specifically terminate the last line in a file and not  add
  32. any  invisible blanks at the end.   When these programs read such
  33. files they will probably abort with a "READ PAST EOF" error.  The
  34. cure is to be sure to enter the final carriage return.   Programs
  35. can  be  written to correct this,  but may  require  an  enormous
  36. overhead  to  check EOF and decide what to do after  every  input
  37. character.
  38. .res
  39.  
  40. .hl 1 INDENTATION CODING
  41.  
  42. A convention widely used in the system is the "indentation__code",
  43. patterned  after  the  coding used  in  the  UCSD  system.   This
  44. expresses an indentation, for a text line, as the character 010h,
  45. or  control-p,  or 16 decimal,  or dle (all synonyms) followed by
  46. the printing character (space + number__of__spaces__to__indent). This
  47. is only a convention,  rather than forced as in the UCSD  system.
  48. All system programs respect this (PASCALP, PAGER, XREF, REFRENCE,
  49. COMPARE,  COPYCOLS,  TYPETEXT, EXPAND) and perform the output 
  50. expansion.  This avoids much useless and time-consuming scanning of
  51. blanks  in text files.   Program COMPRESS creates the indentation
  52. code from plain text.  Of the above programs, COPYCOLS, TYPETEXT,
  53. EXPAND,  COMPRESS  and  REFRENCE are all filters  for  textfiles.
  54. Note that COPYTEXT simply passes on any indentation code.
  55.  
  56. .hl 1 NUMBERED LINES
  57.  
  58. A  further convention used in this system is that textfile  lines
  59. which have an initial string of 8 digits (all must be digits) are
  60. numbered,  and that the first 5 digits are the line number.   The
  61. remaining digits express a fractional line number.  Programs that
  62. process source text,  such as PASCALP,  XREF,  REFRENCE, COMPARE,
  63. PAGER, XREFASSM respect this convention.
  64.  
  65. .hl 1 THE PIP [b] (buffered) OPTION:
  66.  
  67. To co-operate with PIP,  several programs provide for the PIP [b]
  68. buffered  option.   If the programs are executed with a  non-zero
  69. value of parm they will,  at intervals,  emit a dc3 character and
  70. then  pause for approximately parm seconds.   At file  completion
  71. they  will  emit a cntrl-z character.   These cause PIP to  flush
  72. buffers and terminate, and enable simple-minded information 
  73. transfers in printing characters.  Programs that include this feature
  74. are: COPYTEXT, STRIPNUM (both filters), BINHEX and RBMTOHEX 
  75. (documented elsewhere). .bb  The time delays assume execution via
  76. RUNPCD on a 2 Mhz machine (unless the CPMLINK portion has been
  77. customized), .eb or on the HP3000 (or other  machines  with
  78. process  blocking).  An  even value of parm  should  normally  be
  79. specified  to avoid an initial debug trap.
  80.  
  81. .note   WARNING:
  82. some  earlier versions of these programs exist without the  delay
  83. feature.  They should be replaced when found.
  84. .res
  85.  
  86. .hl 1                    MINI-MANUALS
  87.  
  88. .hl 2 COPYCOLS (left__column, right__column) _<infile >outfile
  89.   copies left__column through right__column from infile to outfile.
  90. Left__column defaults to 1, and right__column to 132 (the maximum).
  91. Indentation  codes are expanded before measuring column position.
  92. Lines longer that 132 characters cannot be processed.
  93.  
  94. .hl 2 COPYTEXT _<infile >outfile [optional__parm]
  95.   simply  copies all input to the output.   No indentation  codes
  96. are  expanded.   There is no limit to line length.   The PIP  [b]
  97. option is supported (see above).
  98.  
  99. .hl 2 TYPETEXT _<infile      [>outfile may be specified, but is useless]
  100.   copies infile to "output", normally the user console, and halts
  101. every 20 lines until a _<ret> is entered.   Indentation codes  are
  102. expanded,  and  lines longer that 80 characters are wrapped  into
  103. multiple  lines.   TYPETEXT actually uses another file (KBD)  for
  104. non-echoing  interaction  with the  operator.   This  interaction
  105. reduces its portability.  Some versions may wrap at 79 characters
  106. to allow for terminals that wrap at 80 characters without 
  107. detecting  that  no more characters follow.   An  EndofFile  (control-z
  108. under CPM) when _<ret> is expected ends the pauses permanently. A
  109. control-c at this point exits the program.  [parm] may optionally
  110. be specified,  and alters the default pagesize of 20. Use an even
  111. number to avoid an initial debug trap.
  112.  
  113. .hl 2 EXPAND _<infile >outfile
  114.   is  logically equivalent to COPYTEXT,  but expands  indentation
  115. codes.  There are no provisions for delays etc.
  116.  
  117. .hl 2 COMPRESS _<infile >outfile
  118.   is  the inverse of EXPAND.   Files occupy less disk space,  and
  119. require  less  transmission  time  after  this,   but  are  still
  120. perfectly legible to compilers etc.   They remain comprehensible,
  121. but not pretty, to human viewers.
  122.  
  123. .hl 2 STRIPNUM _<infile >outfile
  124.   removes  any  line  numbers from infile.   See  above  for  the
  125. definition  of a line number.   The PIP [b] option is  supported,
  126. see above.
  127.  
  128. .hl 2 ADDNUMS _<infile >outfile   [optional__parm]
  129.   adds  sequential  line numbers to a textfile.   If a [parm]  is
  130. specified it sets the initial line number -1, i.e. the first line
  131. will be numbered one higher.  This is consistent with the default
  132. zero value of parm.
  133.  
  134. .hl 2 WSTOTEXT _<infile >outfile   [optional__parm]
  135.   is  a preliminary program.   It converts the special characters
  136. in a WordStar document file to the normal Ascii set, removing any
  137. un-used  "soft" hyphens,  suppressing trailing blanks  on  lines,
  138. etc.  In addition any "dot commands" (i.e. lines beginning with a
  139. "."),  and  pagination are deleted.   EOF is correctly set in the
  140. output  file  (see the WARNING  below).   [parm],  if  specified,
  141. serves the same function as the WordStar ".po" dot  command,  and
  142. inserts blank spaces at the left of each line.  This document was
  143. prepared on WordStar and passed through WSTOTEXT.
  144.  
  145. .hl 2 REFRENCE _<infile >outfile
  146.   is  a  highly specialized filter for showing the  structure  of
  147. Pascal source programs,  and respects indentation codes.  It also
  148. follows all _$include filename statements,  and,  if parm=100  was
  149. specified,  follows  all (*$i'filename'*) include commands.   See
  150. the Pascal-P documentation for the specific syntax.   REFRENCE is
  151. a customization of a program by Arthur Sale.
  152.  
  153. All these filters,  with the exception of REFRENCE, are small and
  154. simple  programs.   P-code  versions  of these  filters  are  all
  155. executed  by  the prefix "runpcd ".   Native  code  versions  are
  156. executed as shown.
  157. c¬