home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / txtutl / replace.lbr / REPLACE.DQC / REPLACE.DOC
Encoding:
Text File  |  1986-08-16  |  6.8 KB  |  170 lines
  1.  
  2.  
  3.  
  4.                           REPLACE V1.1
  5.  
  6.  
  7.      REPLACE is a program designed to copy a file, and as it does
  8. so,  to replace certain sets of characters (called KEY STRINGS or
  9. KEYS) with other such sets. Key strings may be specified from the
  10. computer keyboard, or from a previously created disk file.
  11.  
  12. OPERATION:
  13.  
  14.      Type REPLACE and hit a carriage return. You will be asked to
  15. specify  the file in which the replacements are to be  made  (the
  16. INPUT  file),  and  the file to receive the changes  (the  OUTPUT
  17. file).  You  will  then  be asked how the keys are to  be  input,
  18. either  from  the keyboard,  or from a file.  If you  choose  the
  19. keyboard  option  you will be prompted for keys to be  found  and
  20. what  they are to be replaced with.  When you want to  start  the
  21. replacement process, just hit a carriage return when prompted for
  22. the next key to be found.  If the file option is chosen, you will
  23. be  asked  for the name of the file that contains the keys to  be
  24. found  and  replaced  (how to prepare such a  file  is  discussed
  25. below).  The program will then read in the keys,  display them on
  26. the screen, and automatically start the replacement process.
  27.  
  28. SPECIFYING KEYS:
  29.  
  30.      Simple alpha-numeric keys are formed by simply typing in the
  31. letters or numbers you wish to find and replace. Spaces and other
  32. characters  that  appear on the keyboard may also be  entered  in
  33. this fashion, with the exception of the character ^.
  34.  
  35.      ^ may be used to enter characters that do not appear on  the
  36. keyboard,  such  as  control characters and carriage  return  and
  37. line-feed characters. Its use may take four forms.
  38.  
  39. They are:
  40.  
  41. 1) ^^ - represents a single ^ in the key string.
  42.  
  43. 2)   ^A   - where  A  is  any  letter  A-Z.   It  represents  the
  44. corresponding control-character in the key string.
  45.  
  46. 3)  ^(###)  - where  ### is a 1 to 3  digit  decimal  number.  It
  47. represents character number ### of the ASCII sequence in the  key
  48. string.
  49.  
  50. 4)  ^(##H)  - where ## is a 1 or 2 digit hexadecimal  number.  It
  51. represents character number ##H of the ASCII sequence in the  key
  52. string.
  53.  
  54. Using  these forms all ASCII characters 0-255 may be  represented
  55. in either the FIND or REPLACE keys.
  56.  
  57.      The  format of keys is the same,  regardless of whether they
  58. are entered from the keyboard or from a file.
  59.  
  60.  
  61.  
  62. PREPARING A FILE CONTAINING KEYS
  63.  
  64.      A file containing keys may be prepared on any word processor
  65. or  editor that uses ASCII files (WordStar should be used in  the
  66. Non-Document mode).  The file should contain pairs of  lines.  On
  67. the  first line should be the string you want to FIND and on  the
  68. second  line  should be the string you want to REPLACE  it  with.
  69. Pairs  of key strings should be separated by one blank line.  Key
  70. strings  may  be up to 80 in length and there is a  limit  of  30
  71. pairs allowed.
  72.  
  73. USING OPTIONS
  74.  
  75.      Two  options are provided to aid in the use of the  program.
  76. Both  apply  only to the finding of matches between the find  key
  77. and the source text. They do not apply to the replace key.
  78.  
  79.      The first option is to ignore the parity-bits in the  source
  80. file. Some background: there are eight bits used to describe  the
  81. 256 different characters in the ASCII character-set.  Only 7 bits
  82. are needed to specify all of the characters on the keyboard, plus
  83. the  control characters.  The eighth bit (here called the parity-
  84. bit)  is  not normally  used.  However,  some  programs,  notably
  85. WordStar,  use  this  eighth  bit to mark the end  of  words  and
  86. differentiate  between "soft" and "hard"  carriage  returns.  The
  87. default  for  the  program  is to ignore  this  eighth  bit.  For
  88. instance,  the  letter  "E"  will match up  with  both  character
  89. numbers 69 and 196 (=127+69) (decimal) in the ASCII sequence.  If
  90. this option is turned off,  "E" would only match character number
  91. 69.  This option does not affect matches where the eighth bit has
  92. been set in the find key.  ^(196) matches only character 196,  no
  93. matter which option is selected.
  94.  
  95.      The second option directs the program to ignore  differences
  96. in  case when searching for the occurrence of a key in the source
  97. file.   For instance,  if this option is selected "E" will  match
  98. both "E" and "e".  If this option is not selected,  it will match
  99. only "E". The default setting for the program is to pay attention
  100. to differences in case.
  101.  
  102. LIMITATIONS:
  103.  
  104. 1)  The program may run out of memory space if the key strings to
  105. be  replaced are much larger than the keys to be found and  occur
  106. frequently.  If this occurs, the program will terminate with run-
  107. time error FF. To get around this problem, use fewer sets of keys
  108. at one time, or make the replace keys shorter.
  109.  
  110. 2)  If  there is not room on the disk for the  output  file,  I/O
  111. errors F0 or F1 may occur and cause program termination.
  112.  
  113. 3)  The only character that will not work as a find key  in  this
  114. program  is ^Z (control-Z,  ASCII 26 or 1AH) which is used as  an
  115. end-of-file marker.
  116.  
  117. 4) The program is designed for mass replacing.  It does not query
  118. to  be  sure that it only replaces what you want  replaced.  Make
  119. sure  that your keys to be found and replaced are  unique  enough
  120. that only the correct substitutions are made.
  121.  
  122. EXAMPLE
  123.  
  124. In Source file : This is an exameple of some Tex
  125.  
  126.     Find Key 1 : Tex
  127.  
  128.  Replace Key 1 : TEXT
  129.  
  130.     Find Key 2 : me
  131.  
  132.  Replace Key 2 : m
  133.  
  134. In Output file : This is an example of som TEXT
  135.  
  136. Note  that the loss of the letter "e" from the word "some"  would
  137. not have occurred if we had used the find key "ame" (with replace
  138. key "am" instead of just "m").
  139.  
  140. 5) Replaces are done sequentially, in the order in which they are
  141. entered.  This means that if  a replace key (or a portion of)  is
  142. used  later as a find key,  that replace key (or portion of) will
  143. be itself replaced.
  144.  
  145.  
  146. POTENTIAL USES
  147.  
  148. 1)  To  save  keystrokes  when  writing.  Use  abbreviations  for
  149. frequently used words or phrases.   Set up a file containing  the
  150. abbreviations  as  the find keys and the words or phrases as  the
  151. replace keys.
  152.  
  153. 2)  To  rapidly insert print controls while  using  WordStar.  If
  154. there is a word or phrase that needs to be always underlined (for
  155. example : et al.) use the word as a find key (et al.) and for the
  156. replace key,  use the word plus the required print controls (^Set
  157. al^S.).
  158.  
  159. 3)  To  convert  files  from other  word-processing  programs  to
  160. WordStar.  Find ^M and replace it with ^(140) to convert all  the
  161. hard carriage returns to soft ones.
  162.  
  163.  
  164. WordStar is a trademark of MicroPro International Corp.
  165.  
  166. The REPLACE program is free for public distribution,  but may not
  167. be sold without the written authorization of John Porter.
  168.  
  169. Copyright (c) 1985 by John Porter
  170.