home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / f / filt84.lbr / FILT84.HZP / FILT84.HLP
Text File  |  1992-05-09  |  11KB  |  238 lines
  1. ;
  2.                                    FILT 
  3.                                 Version 8.4
  4.  
  5.                                Gene Pizzetta
  6.                                 May 9, 1992
  7.                 Copyright (c) 1984, 1985, 1986 by Irv Hoff
  8.  
  9. FILT, originally written by Irv Hoff, is a ZCPR3 utility that sets or 
  10. expands tabs and removes several types of unwanted characters in ASCII 
  11. text, WordStar documents, or assembler source code files.  A summary of 
  12. what the program found and what it did is presented upon completion.  FILT 
  13. will also run under vanilla CP/M, but can only access the current user area 
  14. in that case (and, of course, the Z features will not work).
  15.  
  16.            U  Usage                         E  Errors
  17.            O  Options                       C  Configuration
  18.            S  Screen Display                H  History
  19.            D  Date Stamping                 B  Bug Reports
  20. :U
  21.  
  22.                                    USAGE 
  23.  
  24.  
  25.      FILT {dir:}infile {dir:}{outfile} {{/}options}
  26.  
  27.  
  28. Only the input filename is required.  If no output filename is given, the 
  29. default is the name of the input file.  Any existing file with the same 
  30. name in the destination directory will be renamed to filetype BAK.  If no 
  31. DIR or DU specifications are given, the current directory is assumed.
  32.  
  33. As distributed, FILT defaults to ASCII text mode.  Control characters 
  34. (except carriage returns and line feeds, but including form feeds) are 
  35. removed, high-bits are reset, and trailing spaces and tabs are removed.  
  36. Lines ending with only a line feed will have a carriage return inserted.  
  37. All tabs are expanded to spaces and then the file is retabbed in 8-column 
  38. increments as long as a tab will replace two or more spaces.
  39. :O
  40.  
  41.                                MODE OPTIONS 
  42.  
  43. Only one mode option should be given.  If more than one is given, the last 
  44. one found will be used.
  45.  
  46.      A    ASCII Text.  This is the default mode (see USAGE).
  47.  
  48.      S    Source code.  Identical to ASCII text mode, except that quoted 
  49.           strings are not retabbed, and even single spaces are replaced by 
  50.           tabs until a semi-colon is encountered.
  51.  
  52.      W    WordStar, no dot commands.  Lines beginning with a period (dot 
  53.           commands) are removed, but ".pa" commands are replaced by form 
  54.           feeds and existing form feeds are retained.  Soft carriage 
  55.           returns and binding spaces are converted to normal.  Soft hyphens 
  56.           at the end of a line are made normal, but other soft hyphens 
  57.           (which are control characters) are removed.
  58.  
  59.      D    WordStar, with dot commands.  Identical to option W, above, 
  60.           except that lines beginning with a period (dot commands) are 
  61.           retained and ".pa" commands are not replaced by form feeds.
  62.  
  63.                               TABBING OPTIONS 
  64.  
  65. Only one tabbing option should be given.  If more than one is given, the 
  66. last one found will be used.
  67.  
  68.      T    Re-tab.  Tabs are expanded to spaces as the source file is read, 
  69.           and then spaces are replaced with tabs (where possible) as the 
  70.           output file is written.  This is the default tabbing mode.
  71.  
  72.      E    Expand tabs.  Tabs are expanded to spaces as the source file is 
  73.           read, but the file is not retabbed.
  74.  
  75.      K    Keep tabs as found.  Tabs in the source file are not expanded to 
  76.           spaces, nor are new tabs added on output.  (Trailing tabs at the 
  77.           ends of lines are still removed, however.)
  78.  
  79.                                OTHER OPTIONS 
  80.  
  81.      F    Retain form feeds.  Normally FILT removes form feeds from ASCII 
  82.           text and source code files.  With this option existing form feeds 
  83.           will be kept.  (Form feeds are always kept in WordStar modes.)
  84.  
  85.      Q    Quiet mode toggle.  If the ZCPR3 quiet flag is on, FILT defaults 
  86.           to quiet mode.  In that case, this option puts FILT in verbose 
  87.           mode.  If the quiet flag is off, this option puts FILT into quiet 
  88.           mode.  In quiet mode all screen output is suppressed except error 
  89.           messages and the usage screen.
  90.  
  91. A leading slash is required before the option list only if the options are 
  92. not the third token in the command tail, but is allowed in any case.  All 
  93. options can be configured as defaults (see CONFIGURATION).
  94. :S
  95.  
  96.                               SCREEN DISPLAY 
  97.  
  98. By default an incrementing line count is displayed while FILT is working.  
  99. The final summary screen varies depending on the current file mode.  The 
  100. default summary shows counts of the total lines in the file, original 
  101. spaces, original tabs, current spaces, current tabs, form feeds deleted, 
  102. high bits zeroed, control characters deleted, orphan line feeds fixed, and 
  103. trailing spaces deleted.
  104.  
  105. In WordStar mode, the display shows the number of form feeds present, since 
  106. they are not deleted.  It also adds counts for dot commands deleted (with 
  107. option W), dot commands retained (with option D), soft carriage returns 
  108. fixed, soft hyphens fixed, and binding spaces fixed.
  109. :D
  110.  
  111.                                DATE STAMPING
  112.  
  113. Under ZSDOS the create date stamp of the source file will be transferred to 
  114. the destination file.
  115.  
  116. If the source file has no create date, but has a modify date, the modify 
  117. date will become the create date of the destination file, so the earliest 
  118. available date is preserved.
  119.  
  120. If the source file has neither a create date nor a modify date, no date 
  121. stamp transfer is done.
  122. :E
  123.  
  124.                                   ERRORS 
  125.  
  126. On error the ZCPR3 program error flag is set as follows:
  127.  
  128.        2  Invalid directory
  129.        4  File read error or file close error
  130.        8  Ambiguous filename
  131.       10  Source file not found
  132.       11  No disk or directory space
  133.       19  Invalid option
  134.      255  User abort (^C)
  135.  
  136. Whether a user abort via ^C generates an error is a configurable option 
  137. (see CONFIGURATION).  All errors cause the error handler to be invoked.
  138. :C
  139.  
  140.                                CONFIGURATION 
  141.  
  142. Although distributed ready-to-run under both ZCPR3 and vanilla CP/M, FILT 
  143. offers several configuration options for those not satisfied with the 
  144. defaults.  The default modes for all the command line options can be 
  145. changed.
  146.  
  147. In addition, the running line count progress report, which FILT normally 
  148. displays while it is working, can be suppressed.
  149.  
  150. FILT can also be configured to generate an error when the user aborts via 
  151. ^C, thus invoking the error handler.  This feature can be handy for halting 
  152. SUB and ZEX batch operations.
  153.  
  154. Configuration is accomplished using Al Hawley's ZCNFG with the accompanying 
  155. FILTnn.CFG file.  Built-in help screens explain the configuration choices.  
  156. If you don't change the name of the CFG file, ZCNFG will always be able to 
  157. find it even if you change the name of FILT.
  158. :H
  159.  
  160.                                   HISTORY 
  161.  
  162. Version 8.4 -- May 9, 1992 -- Gene Pizzetta
  163.      At Howard Goldstein's suggestion, I added a new command line option to 
  164.      allow retaining existing form feeds in ASCII text and source code 
  165.      files.  This new option is also configurable as the default.  
  166.      Appropriate modifications have been made to FILT84.CFG and to 
  167.      FILT84.HLP.
  168.  
  169. Version 8.3 -- May 3, 1992 -- Gene Pizzetta
  170.      On systems without date stamping, FILT was trying to rename files in 
  171.      the wrong directory.  That has been fixed.  Thanks to Ed Flinn and 
  172.      Howard Goldstein for finding this bug.  While I was at it, I have 
  173.      changed the DOC file to a standard ZCPR3 help file.
  174.  
  175. Version 8.2 -- March 3, 1992 -- Gene Pizzetta
  176.      A request from Howard Goldstein has motivated me to add the ability to 
  177.      keep tabs in the document as originally found.  This three-way 
  178.      operation has resulted in two new command line options: E to expand 
  179.      tabs to spaces and K to keep them as found.  Trailing tabs will still 
  180.      be removed.  Whether a user abort via ^C generates an error is now 
  181.      configurable.  Should now be CP/M compatible in the current user area 
  182.      only.
  183.  
  184. Version 8.1 -- September 30, 1991 -- Gene Pizzetta
  185.      FILT did not check for ambiguous filenames (and never has), which 
  186.      could cause a small disaster.  It checks now.  Made display of line 
  187.      count progress reports into a configurable option.
  188.  
  189. Version 8.0 -- September 10, 1991 -- Gene Pizzetta
  190.      Disassembled enough to change to a relocatable file (it was easy after 
  191.      working on JUSTIFY).  Changed to Z80 opcodes to partially compensate 
  192.      for space used by additional features.  Replaced some routines with 
  193.      library routines.  Now allows destination directory without 
  194.      destination filename.  Changed key options to command line entry.  
  195.      Changed some messages to make them more descriptive.  Added DU 
  196.      support, intelligent usage screen, error flag setting, error handler 
  197.      invocation, quiet mode, and ZCNFG configuration.  Under ZSDOS and 
  198.      ZDDOS file create date stamps are transferred to the new file.  
  199.      Incorporates some code efficiencies suggested by Bruce Morgen for 
  200.      JUSTIFY.  The hardest part of this conversion was deciding how to make 
  201.      those various interactively chosen modes into a group of logical 
  202.      command line options.  I hope I've succeeded.
  203.  
  204. Version 7.0a -- May 11, 1986 -- Irv Hoff W6FFC
  205.      When filtering WordStar files FILT7 was checking for unwanted control 
  206.      characters too soon, thus ignoring space breaks and soft-hyphens.  The 
  207.      summary report then indicated none were found.  That has been fixed 
  208.      with FILT7A.  Evidently these characters are seldom used in WordStar 
  209.      files, as I had to make some special files to even test this feature.  
  210.      This would be verified to some extent by nobody calling this to our 
  211.      attention even though the program has been available for several years 
  212.      now.  (WordStar uses 0Fh for space breaks and 1Fh for soft-hyphens.)
  213.  
  214. Version 7.0 -- April 27, 1985 -- Irv Hoff
  215.      Accepts lines up to 255 characters long (vice 128).  Insures last line 
  216.      has CR-LF to allow normal processing.
  217.  
  218. Version 6.0 -- March 7, 1985 -- Irv Hoff
  219.      Added tab option if in Text mode.  Fixed ERXIT so external file is not 
  220.      deleted unless a 'Y' is used.
  221.  
  222. Version 5.0 -- November 20, 1984 -- Irv Hoff
  223.      Initial version, similar style to FORM5, NEAT5 and TABS5.
  224. :B
  225.  
  226.                         BUG REPORTS AND SUGGESTIONS 
  227.  
  228. Please report any bugs as soon as possible, and make suggestions at your 
  229. leisure:
  230.  
  231.                   Gene Pizzetta
  232.                   481 Revere St.
  233.                   Revere, MA 02151
  234.  
  235.                   Voice:  (617) 284-0891
  236.                   Newton Centre Z-Node:  (617) 965-7259
  237.                   Ladera Z-Node Central:  (213) 670-9465
  238.