home *** CD-ROM | disk | FTP | other *** search
/ Loadstar 128 22 / q22.d81 / indexer.doc < prev    next >
Text File  |  2022-08-28  |  28KB  |  661 lines
  1.  
  2.  
  3.  
  4.                                                  Indexer 128 by e.g.bell
  5.  
  6.  
  7.  
  8.         Over the years, the most frequent complaint I have seen about
  9.         software is in regard to the documentation.  Good documentation
  10.         plays a large part in the success of a program.  People have to
  11.         know how to use it.  At best, a poorly documented program will
  12.         not be fully utilized.  At worst, it will not be used.
  13.         
  14.         Successful documentation involves familiarity with the program
  15.         and ability to express the features, functions, and requirements
  16.         clearly.  A certain amount of style goes a long way toward
  17.         making it interesting also.  Though style and the ability to
  18.         convey the information rest with the documenter, there are two
  19.         features you will find in virtually all good documentation which
  20.         anyone can do professionally, and with Indexer 128, easily.
  21.         These features are a table of contents and an index of key words
  22.         which serve as a quick reference to things covered in the text.
  23.         
  24.         Documentation is tedious at best, even for the person who
  25.         created the program.  Creating a table of contents may prove to
  26.         be a relatively painless task for shorter documents or those
  27.         which don't change often, because you are usually dealing with a
  28.         limited number of entries.  An index, on the other hand, is a
  29.         potential nightmare for a sizable project.  This is a nightmare
  30.         I faced.  Documentation for one of my programs was in excess of
  31.         190 thousand bytes, a 152 page document.  It was divided into 45
  32.         sections, each referenced in my table of contents.  There was an
  33.         index of 102 words and phrases which served as quick references
  34.         to various features and functions documented in the text.  It
  35.         was made up of six linked files, three of which each consumed
  36.         the whole buffer in The Write Stuff.  
  37.         
  38.         I wanted a professional manual.  My decision, my method, was to
  39.         'print' the whole document to disk as ONE sequential ASCII text
  40.         file.  My documentation, in this format, takes up over 800 disk
  41.         blocks.  How would you like to index that?
  42.         
  43.         I selected this sequential ASCII text format because it allowed
  44.         me to ignore control and escape sequences particular to various
  45.         word processors and concentrate only on the task I really needed
  46.         performed.  The file was on disk exactly as it would be on
  47.         paper, in one package, ready to yield the information I wanted.
  48.         In addition, this made the process available to ANY word
  49.         processor able to 'print' data to disk in sequential format.  In
  50.         this regard, there is one caution.  If you have made use of
  51.         formats a disk can't recognize, italics, underlining, and such,
  52.         make a copy of the file without these before creating your
  53.         Document file.  Things like centering, margins, page length,
  54.         etc. require no such consideration however.  In addition,
  55.         obviously for files the size of my documentation file, you'll
  56.         need a 1571 ,1581, RamLink, or one of the other high capacity
  57.         storage devices sold by Creative Micro Designs.  But for files
  58.         up to 664 blocks, you can use a 1541.
  59.         
  60.  
  61.  
  62.  
  63.  
  64.                                      Page 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                                  Indexer 128 by e.g.bell
  71.  
  72.  
  73.  
  74.         Indexer processed my 832 block documentation file in just over
  75.         seven minutes.  That included the 45 entry table of contents and
  76.         over 750 page-references for the 102 words/phrases.  The search
  77.         words spanned a wide spectrum, from REU to Modem Selection.
  78.         Your results will be different, affected by the length and
  79.         format of your document, the words and phrases you specify, etc.
  80.         One thing, however, will be the same.  You'll be pleased with
  81.         the results!
  82.         
  83.         *** On With The Show
  84.         
  85.         When you run Indexer 128, the first thing you will be asked is
  86.         if you want to 
  87.         
  88.         <C>reate      <P>rint     or   <Quit>
  89.         
  90.         Printing will print a table of contents or index (or any text
  91.         file) from the 'target' drive.  That is the way it is set up.
  92.         Indexer 128 will make sure you enter the needed information, and
  93.         make sure it is correct also.  See the section on the source
  94.         file names below for getting directories, and the section toward
  95.         the end of this document regarding DOS commands.
  96.         
  97.         *** What You Get
  98.         
  99.         The output can be in CBM ASCII, screen code [as used by
  100.         Speedscript and The Write Stuff], or True ASCII, if that is
  101.         required.  This was to allow easy formatting of the finished
  102.         files with a word processor if desired.  You can also use
  103.         Indexer 128 to dump existing Index and Contents files (or any
  104.         text  file for that matter) to printer.  Just follow the
  105.         prompts.
  106.         
  107.         The net effect of this, then, is that you can take files created
  108.         by Indexer 128 and load and edit, print, or link them to any
  109.         other file created with that word processor or editor.
  110.         
  111.         *** Document Preparation
  112.         
  113.         I originally considered doing all of this searching in RAM but,
  114.         as I mentioned previously, some of my files were just too large.
  115.         In addition, this would have required processing of linked
  116.         files, format commands, etc.  I felt this would be too much
  117.         work, duplicating functions the word processor already
  118.         performed.  Thus, the index and the table of contents are
  119.         created from a document filed on disk.  This can be as large as
  120.         a disk will allow, up to 3160 blocks for a 1581 drive, and a
  121.         world larger for some of the new CMD mass storage devices like
  122.         RamLink or the HD or FD drives.
  123.         
  124.         Indexer 128 allocates 6144 bytes, 6K, for handling pages of the
  125.         document.   It assumes you are using documents in 80 column
  126.  
  127.  
  128.  
  129.  
  130.                                      Page 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                                  Indexer 128 by e.g.bell
  137.  
  138.  
  139.  
  140.         format on 66 line pages, although there is some room for
  141.         variety.  Still, this 6144 bytes will handle 75 lines of 80
  142.         characters each, so you can see it is over-qualified for
  143.         anything likely to be thrown at it.  You will probably never see
  144.         a document of even 66 lines containing 80 characters in every
  145.         line, and there are other factors that make this capacity even
  146.         more lofty.  They will be discussed later in this document.
  147.         
  148.         As stated previously, Indexer 128 requires this file to be in
  149.         ascii text format, literally printed to disk instead of the
  150.         printer.  It may be in either true ASCII or PETSCII format on
  151.         the disk.  Indexer 128 will process all of that 'on the fly'.
  152.         
  153.         *** To Disk In Sequence
  154.         
  155.         You might wonder exactly how to get your file to disk in
  156.         'sequential ASCII file' format with your word processor,
  157.         particularly if you use a screen code type word processor.  How
  158.         about a couple of common examples!
  159.         
  160.         If you use Speedscript, first press Shift-Control-P.  Then, at
  161.         the status line prompt, press 'D' for disk.  Select and enter a
  162.         name for your file when you are asked to do so.  
  163.         
  164.         If you use The Write Stuff, use the ^ to put the cursor on the
  165.         status line, then move the block cursor over the word 'Print'.
  166.         At the next menu, move the block cursor over 'Disk'.   Enter a
  167.         name for your Document.  If you are processing a group of linked
  168.         files, answer 'YES' when asked.
  169.         
  170.         Using this method, all controls and word-processor-specific
  171.         functions are taken care of by the program designed to take care
  172.         of them... the word processor.
  173.         
  174.         *** In The Beginning The Word Was...
  175.         
  176.         The search file must also be