home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / wstar / index.dqc / INDEX.DOC
Encoding:
Text File  |  1985-02-10  |  10.8 KB  |  397 lines
  1.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 1
  2.  
  3.  
  4.  
  5.                   You  can do anything you want with this program  except 
  6.              sell  it.  Give  it to anyone who wants  it.  Address  bugs, 
  7.              suggestions, etc. to:
  8.  
  9.                   Tom Jennings
  10.                   221 W. Springfield St.
  11.                   Boston MA 02118
  12.  
  13.                   Leave me a message at NECS CBBS.
  14.  
  15.                   INDEX is a utility for use with WordStar, and generates 
  16.              an alphabetically sorted index for a file.  Words or phrases 
  17.              to  be put in the indexed are marked with control characters 
  18.              not used elswhere within WordStar.  (At least as of  version 
  19.              1.01)  If a file is later edited,  invoking INDEX again will 
  20.              remove the old index,  produce a new one,  and add it to the 
  21.              end of the file.
  22.              
  23.                   INDEX can also be use with any non-WordStar text editor  
  24.              that  can insert control characters into the text.  No other 
  25.              assumptions are made about the contents of the file,  except 
  26.              that  the  file  is  terminated  by  a  control-Z  character 
  27.              (correct way) or end of file.
  28.  
  29.                   INDEX  scans  the text file for certain  WordStar  "dot 
  30.              commands",  such as page breaks,  etc., in order to maintain 
  31.              proper page numbers. If no page "dot" commands are found, as 
  32.              with other editors, pages are counted internally. 
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 2
  68.  
  69.  
  70.  
  71.                   There are two different kinds of index  entries;  WORDS 
  72.              and  PHRASES.  WORDS  are  what are normally thought  of  as 
  73.              words;  groups of characters,  seperated by  spaces,  commas 
  74.              carriage  returns (called CR from now on) or linefeeds (LF). 
  75.              PHRASES  are  groups of words,  including  the  spaces  that 
  76.              seperate the words. 
  77.  
  78.                   Since  words are easy to find,  only a single marker is 
  79.              necessary  to  identify them.  This marker  is  a  control-K 
  80.              character,  ^K.  Phrases  must  have both ends  marked,  and 
  81.              control-P is used, ^P. Below are some examples:
  82.  
  83.              The sixth word in this ^Ksentence will be put in the index.
  84.  
  85.              ^PThis entire phrase will be there^P, also.
  86.  
  87.                   Since this is page 2 of the manual, the index for these 
  88.              should look like:
  89.  
  90.              Sentence...................................... 2
  91.              This entire phrase............................ 2
  92.  
  93.                   These two examples are actually in the index at the end 
  94.              of this manual.
  95.  
  96.              WordStar dot commands
  97.  
  98.                   INDEX is optimized for use with WordStar.  By  default, 
  99.              it  scans  the  file for "dot  commands";  notably  .pa  and 
  100.              "..index". .PA is used to count pages, and must be the first 
  101.              word on the line to be counted as a dot command. 
  102.  
  103.                   The "..index" is created and used by INDEX.  As defined 
  104.              in  the  WordStar manual,  any line beginning with two  dots 
  105.              (..) will be ignored when printed.  INDEX uses this to  mark 
  106.              the beginning of the index.  When INDEX is run,  if it finds 
  107.              the  "..index" line,  it will remove all text following that 
  108.              line. This allows creating an index for an updated file that 
  109.              already has an index. If one was not found, it is added.
  110.  
  111.                   CAUTION: NEVER put a ".." WordStar dot command followed 
  112.              by index,  as described above.  All text following this line 
  113.              will  be deleted from the file.  A single space after the .. 
  114.              will suffice, or use .IG instead.
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 3
  134.  
  135.  
  136.              Sorting
  137.  
  138.                   As  stated  before,   the  index  generated  is  sorted 
  139.              alphabetically.  The  entire  phrase  or  word  is  used  in 
  140.              sorting,  except  that  case is ignored.  
  141.  
  142.                   If  identical entries are found,  they are listed on  a 
  143.              single  line,   followed  by  all  page  numbers  found  on. 
  144.              Unfortunately,  multiple  identical  page  numbers  will  be 
  145.              listed.  For  clarity,  some  examples of  how  things  work 
  146.              follows.
  147.  
  148.              The  following  two  phrases  are  equivalent,  as  case  is 
  149.              ignored, and will be listed on one line. The first occurence 
  150.              will be the entry on the left side of the page.
  151.  
  152.              This is the first phrase
  153.              THIS IS THE FIRST PHrAsE
  154.  
  155.              Since length counts, these next are all in proper order.
  156.  
  157.              This
  158.              This is
  159.              This is what
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 4
  200.  
  201.  
  202.              Side effects and cautions
  203.  
  204.                   This is a list of implementation peculiarities, etc.
  205.  
  206.              -In general, any group of one or more white-space characters 
  207.              (see  below)  are converted into a single  space  character. 
  208.              Phrases  with  embedded spaces will have  all  extra  spaces 
  209.              (more  than  one)  removed.  A phrase may start and  end  on 
  210.              different  lines  (or even pages) and  will  work  properly. 
  211.              Leading spaces will be removed from the index entry.
  212.  
  213.              -The  following characters are converted to and treated as a 
  214.              single ASCII space character.  These also mark the end of  a 
  215.              word:
  216.  
  217.                           CR LF tab comma (,) semicolon (;) 
  218.                               colon (:) suprise-mark (!)
  219.             
  220.              -BUG  NOTICE Periods are removed from the character  stream. 
  221.              This was a cheap way out since it is a  sentence-terminator. 
  222.              The  only  time this is a problem is when putting things  in 
  223.              the index such as filenames. (i.e., FILENAME.TYP) If someone 
  224.              complains, it will probably get fixed.
  225.  
  226.              -BUG  NOTICE     The buffers for the indexed words is in  an 
  227.              array in memory.  Like most of my kludges,  there is minimal 
  228.              error  checking  done.  There is currently a limit  of  1000 
  229.              decimal words/phrases per index,  and there is a 32768  byte 
  230.              buffer made for them. If you only have 40K of memory....
  231.  
  232.              -ANNOYANCE      WordStar  control characters,  such  as  ^B, 
  233.              count as legal characters, but are not printer in the index. 
  234.              So,  if you indexed two words,  ^K^Bfoo and ^Kfoo, they will 
  235.              get seperate entries.
  236.  
  237.              -GOOD  THING     INDEX assumes you do not want to lose  your 
  238.              source  file,  and does all work in  temporary  files.  When 
  239.              invoked,  it generates a file name.IDX, and copies the input 
  240.              file  to it as it looks for words.  (see note on ..index and 
  241.              EOF) Then,  the index is put in it,  and the file is closed. 
  242.              Then  if  all  is OK,  any file  name.BAK  is  deleted,  the 
  243.              original name.ext renamed to name.BAK,  and name.IDX renamed 
  244.              to name.ext.
  245.  
  246.              -Words and phrases will have any leading spaces removed. The 
  247.              first  character of any word or phrase will be converted  to 
  248.              upper  case.  Note  that  if a phrase consists of  a  single 
  249.              blank,  it will NOT be removed from the index. This does not 
  250.              count  for words,  of course,  as the next word  that  comes 
  251.              along will be indexed.
  252.  
  253.              -Because  of wonderful CP/M,  and the fact that some of it's 
  254.              utilities  use end-of-file instead of a control-Z  character 
  255.              to  terminate text,  INDEX cannot detect the following  read 
  256.              errors: unwriten random record, zero length.
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 5
  266.  
  267.  
  268.  
  269.              -INDEX sorts in ASCII order.  Digits,  quotes,  parenthesis, 
  270.              etc come before letters.
  271.  
  272.              -The  sort routine used is horrible.  It uses a bubble sort, 
  273.              with  extra  unnecessary  exchanges.   Didn't  require  much 
  274.              thought, though.
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  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.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.          Text file INDEX generator (c) T.Jennings 7/21/81    Page 6
  332.  
  333.  
  334.                 Colon...................................  4
  335.                 Comma...................................  4
  336.                 Control-Z...............................  4
  337.                 CP/M....................................  4
  338.                 CR......................................  4
  339.                 Embedded spaces.........................  4
  340.                 End-of-file.............................  4
  341.                 Examples................................  2
  342.                 Filenames...............................  4
  343.                 INDEX...................................  1
  344.                 Leading spaces..........................  4, 4
  345.                 LF......................................  4
  346.                 Non-WordStar text editor................  1
  347.                 Periods.................................  4
  348.                 PHRASES.................................  2
  349.                 Semicolon...............................  4
  350.                 Sentence................................  2
  351.                 Side effects and cautions...............  4
  352.                 Suprise-mark............................  4
  353.                 Tab.....................................  4
  354.                 This entire phrase will be there........  2
  355.                 White-space characters..................  4
  356.                 WORDS...................................  2
  357.                 WordStar................................  1
  358.                 WordStar "dot commands".................  1
  359.                 WordStar dot commands...................  2
  360.                 ^B......................................  4
  361.                 ^K......................................  2
  362.                 ^P......................................  2
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.