Gold Fish 2/goldfish_vol2_cd1.bin/files/text/show/want/docs/want.doc

Text File | 1994-07-20 | 22KB | 583 lines

                              WANT

                 Searches Documents for Keywords

                 Requirements......Hardware & Software
                 Installation......A New Concept
                 Using WANT........Operating Instructions
                 CLI Usage.........Command Line Template
                 WB Usage..........Tooltypes
                 Menus & Help
                 Wildcards.........*
                 Hot Tips..........For Advanced Users
                 GNU Disclaimer....License
                 About BOTH........Credits & Distribution

                 By BOTH Software
                 GiftWare  © 1994



  --------------------------------------------------------------------
                 SYSTEM REQUIREMENTS  VERSION 1.017
  --------------------------------------------------------------------

  WANT needs: WB 2.x and up - Any Amiga
              AmigaGuide, or another text reader
              About 1 Meg of memory to hold a file.
              A Hard Drive would be nice, but not necessary.


  --------------------------------------------------------------------
                 How to install WANT
  --------------------------------------------------------------------

 WANT is distributed in a single directory. Copy that directory and
 it's drawer icon to any place on your hard drive. The first time you
 run WANT, it will make all the necessary assigns to add itself to the
 system. (No more modifications to the startup-sequence!). The
 ASSIGNS are temporary. They will last only until you turn off the
 power or reboot.

 WANT makes these ASSIGNs to the system:

 WANT: DH?:WANT
 LIBS: WANT:libs ADD

 Caution: Do not make WANT resident.
          Do not move files out of WANT's directory.

  --------------------------------------------------------------------
               Calling WANT from the CLI
  --------------------------------------------------------------------

 TEMPLATE:

 WANT SOURCE,FILEREADER/K,EDITOR/KCOLOR/K,NOHIGHLIGHT/S,HIGHLIGHT/S,
      BOLD/S,ITALIC/S,UNDERLINE/S,REVERSE/S

 For a complete description of these command options, refer to the
 tooltypes section.

 Unlike the tooltypes, you do not have to enter the full path for
 EDITOR and FILEREADER as long as they are in the path.

 These commands are not positionally sensitive.

 If you simply enter WANT, the program will run with built-in defaults
 for the filereader, editor, highlighting and color.

  --------------------------------------------------------------------
           OPERATING INSTRUCTIONS FOR WANT
  --------------------------------------------------------------------

What does WANT do for you?

 WANT will search a textfile, like INDEX, for instances of words you
 supply. For example, let's say you have the AmiNET INDEX file that
 lists all the files available from that mirror site. You want to know
 if a file called AGATE is in the list. WANT will search the file,
 looking for any instance of the word AGATE. Each line of the INDEX file
 that contains the word AGATE will be displayed on the screen.

 Let's try another example using INDEX - you want to find all the
 lines that contain the words DATATYPE and GIF. WANT will display any
 lines that have both words in it. WANT will also find lines with
 DATATYPE or GIF, thus narrowing your search. Use the cycle gadget
 labelled AND OR to select the function to use.

The Execute button

 Want gives you many options to select from the operating panel. After
 you select all of the options necessary, click the Execute button.
 This button tells WANT to begin retrieving the information you asked
 for.

Selecting a File with the File Requester

 You must select a file to search or view. If you forget, WANT will
 prompt you select a file from the file requester.

 The requester used in WANT was custom written for this application.
 It has some features you may not have seen before. To select a file
 or directory, just click the mouse once. Multiselection is not
 supported. The four buttons at the bottom are:
 PARENT, DRIVES, VOLUMES, and DIR.

PARENT
 This button will select the directory above the one you are in. There
 is another, faster, way to invoke PARENT. Place the mouse pointer against
 the left edge of the screen and press the Left Mouse Button.

DRIVES
 This will display all the physical devices attached to your Amiga. It
 will show hard drives, floppys, CD players, RAM, RAD, and others.

VOLUMES
 This will display all ASSIGNS and VOLUMES seen by the system.

DIR
 Since the Amiga is a multitasking beast, you might leave WANT to do
 something else and then come back. The contents of the requester may
 have changed in the meantime. By pressing DIR, the directory listing
 is updated.


Viewing a Text File without searching for terms

 WANT will also display any selected file with the filereader of your
 choice. To read a selected file, select the "View a file" option
 then click Execute. You cannot search for terms when in this mode.

Redirecting the output to a Text Editor

 Instead of a filereader, you may direct the output of WANT to the text
 editor of your choice. To do this, select the "Search and Edit" option.
 This option works like "Search and View", but no highlighting is
 permitted (or wanted). The default EDITOR is ED, but you can change
 that to your favorite with the tooltype. Be sure to include the full path
 to the editor.

 If you want to edit an entire file with the editor:

      Select a file
      Enter an asterick (*) as the ONLY search term
      Select "Search and Edit"
      Execute

 This will bring the entire file into your editor. Remember to
 SAVE AS when you save an edited file. The filename has been changed.

 The Asterick (*), as a single search term, is considered a wildcard,
 meaning all lines of the file will be 'found' and displayed.

 Also see wildcards

Highlighting words found by a search

 The word or words you asked to see are, by default, bolded. This
 helps you locate the word more quickly. You can change the kind of
 highlighting with the checkboxes labelled BOLD, ITALIC, UNDERLINE,
 and REVERSE. You may use any or all of these options. Experiment
 with the buttons to see which type of highlighting you prefer.

 The checkmark box on the screen labelled HIGHLIGHT will allow you to
 disable the highlighting when checked.

Clearing the text entry fields

 The button called CLEAR will erase the two text entry fields so you
 may enter new data. These fields can be erased individually by
 pressing Control X.

Displaying extra lines on a search

 Not all files are as predictable as a mirror's INDEX. For example,
 the file you want to search may be an email letter or DOC file.
 By simply asking WANT to find a word and display the line that
 word was found in, you won't be able to see the word in it's
 proper context. Ideally, you would like to see a few lines before
 the word and a few lines after the word. The gadgets labelled
 LEADING LINES and TRAILING LINES let you select how many lines
 to display before and after the line with the word in it.

Whole Word searches

 Normally, WANT will find a search term within another word. For
 example, if you ask for bet, WANT will find better.
 If you want to search for examples of whole words, just check the
 Whole Words box. Now your entty will be treated as if you typed a
 space before and after the word.

Case Sensitivity

 Normally, WANT will treat your entries without regard to Case. If you
 need the case to be sensitive, check the Case Sense box.

A pecularity of AmigaGuide

 If you use AmigaGuide as your filereader, you may find that searching
 an AmigaGuide document can give unpredictable results. If your search
 term is found in a line that begins with @NODE, AmigaGuide will get
 very confused. To see the results properly, try using the editor or a
 different filereader.




 For more detailed instructions on the operation of WANT and some
 ideas on how to use it to your advantage, see hot tips.

  --------------------------------------------------------------------
                     PULL DOWN MENUS
  --------------------------------------------------------------------

Pull-Down Menus

     PREFS
     HELP
     ABOUT
     QUIT

 Prefs is ghosted and not available in this version.

 Help will display this AmigaGuide file if your selected filereader
 is AmigaGuide. If you have selected another filereader, like More,
 the file called WANT.doc will be substituted.

 About will display information about BOTH Software.

 Quit will exit the program.

  --------------------------------------------------------------------
                    WILDCARDS
  --------------------------------------------------------------------

 The Asterick (*), as a single search term, is considered a wildcard,
 meaning all lines of the file will be 'found' and displayed.

 The Asterick (*), when used as part of a search term means anything
 following is selected automatically. An example: gfx* will find any
 line with gfx and will highlight any characters following gfx. It
 would look like this:

 Videotracker2.lha   gfx/misc   395K+Let graphics react to sound

 Another example: gfx*n will search for gfx and will highlight until
 it finds an "n".

 picmerge.lha     gfx/conv 11K+Little utility for connecting 2

 "*" will find anything enclosed in double quotes.

 "* will find the first quote mark in a line but highlighting will
 not occur.

 * and Whole Word will not work. The terms are too vague for GAWK to
 interpret.

 The Asterick follows the UNIX rules of the Period. Using an Asterick
 can result in unexpected highlighting results. We recommend you use
 caution for this reason.

  --------------------------------------------------------------------
          RUNNING WANT FROM THE WORKBENCH
  --------------------------------------------------------------------

Customizing the look of WANT

      This section covers the tooltypes available for WANT.
      If you are not familiar with tooltypes, please refer
      to the operating instructions provided with your Amiga.


 WANT will accept five tooltypes:

 FILEREADER, EDITOR, HIGHLIGHT, COLOR, SOURCE

 If for any reason the tooltype you invoke does not seem to work,
 please examine your entry for spelling or syntax errors. WANT will
 not report these errors to you. To remove a tooltype, enclose it in
 parentheses, then SAVE.

 We all have our favorite filereaders. WANT won't limit you to using
 any one filereader. You may specify the reader of your choice in the
 icon's tooltype.

 The default filereader is AmigaGuide. If you prefer More or MultiView,
 or any other reader, just change the tooltype. The proper syntax is:

     FILEREADER=DH0:UTILITIES/MULTIVIEW

 The filereader MUST include the full path, like this:

     FILEREADER=DH2:TEXTREADERS/LOOKER

 Note: WANT expects to find More in SYS:UTILITIES. This is an
 internal default that you cannot change. This is done so that WANT has
 a standard default in case AmigaGuide is not present on your drive.
 If you are using V34 of the AmigaGuide.library, WANT will automatically
 turn off highlighting, since this version will not allow it.

 Several filereaders were tested for compatibility with WANT. Here are
 some that worked well with WANT:

     AmigaGuide
     Multiview
     More
     MuchMore
     PPMore
     CType

     Etale:  (efr) will not show colors, but works well in
             all other respects. If you use this reader, set
             the color tooltype to:  (COLOR=)
     View80: Will not display highlighting or colors. To use
             View80, enter the tooltype HIGHLIGHT=OFF.

 For more on Filereaders, see Hot Tips

 You may direct the output of WANT to a text editor. The tooltype is
 EDITOR. You MUST enter the full path of the text editor.

     EDITOR=SYS:C/ED

 Highlighting is set to OFF when using the editor. This way, the
 output file will not contain any of the Escape characters that
 WANT uses for highlighting.


Highlighting options

 When WANT gets a 'hit' on a keyword, that word is highlighted in any
 combination of the following ways:

     Bold   Underline  Italic  Reverse

 Bold is the default, but you may change to any other. You may
 actually select all of them, but before you do that, test the effect
 first by checking the boxes on the GUI. Whatever highlighting
 options you select in the tooltypes will be reflected as default
 values on the screen.

 To set the highlighting options in the icon, follow these examples:

     HIGHLIGHT=ITALIC
     HIGHLIGHT=REVERSE|BOLD
     HIGHLIGHT=BOLD|ITALIC|REVERSE

 Notice the vertical bar separating the options. This is the SHIFTED
 BACKSLASH key. By using the vertical bar, you may select more than
 one option.

 You may choose not to have Highlighting and Colors as a default. Select
 this by adding the word OFF to the HIGHLIGHTING tooltype. Example:

     HIGHLIGHT=OFF
 This option will disable all highlighting modes and colors.


Colors

 The highlighted words can be made to print in one of the four basic
 colors of the WorkBench. You may have reset these color values from
 the original Gray, Black, White, and Blue. WANT can't tell what
 shades are actually being displayed. You will have to be the final
 arbitor of the colors. You may select, through the COLOR tooltype
 any one of these colors. Black is the default. If you have changed
 the palette preferences, Black may now be Mauve. You may have to
 experiment. Remember, select only one color:

     COLOR=WHITE  (or BLACK, BLUE, GRAY)

Default Directory

 Through the use of the SOURCE tooltype, you can select the path and
 filename that WANT will display in the listview. If you usually
 search files in the same directory, this is a timesaving feature. You
 can specify a directory or a directory and a filename. Here are some
 examples:

     SOURCE=AAMYFILES:
     SOURCE=AAMYFILES:INDEX

Tooltype Summary

     FILEREADER=<path>filereadername

     EDITOR=<path>texteditor

     HIGHLIGHT=OFF
               BOLD
               ITALIC
               UNDERLINE


     COLOR=WHITE
           BLACK
           BLUE
           GRAY

     SOURCE=<path><filename>

  --------------------------------------------------------------------
                    Hot Tips
  --------------------------------------------------------------------

     How to get the most from WANT

 You'll find that you usually search the same files. To search them
 quickly, make a directory called myfiles and put your favorite files
 in this directory. Then enter the following line in your
 startup-sequence:

     ASSIGN aamyfiles: <path>myfiles

 Notice the 'aa' preceeding the name. From WANT, click the VOLUMES
 button. The lists all the logical assigns made on your system, alpha-
 betically. The 'aa' will insure this ASSIGN is at the top of the list,
 making it easier for you to find it.

 What can you put in this directory? RECENTS and INDEXES for a start.
 Fred Fish listings, FAQs, articles, readmes, docs, and anything else
 you might want to look through. This method eats up some disk space,
 but saves you the hassle of hunting through directories to find files.

 When you search Fish listings, its a good idea to choose about 25
 lines of leading and 5 lines of trailing context. You may adjust these
 numbers at any time. The more lines you select, the longer the search
 will take. (The filereader will take longer to load the file).

 Do you ever use FIND to locate a file on your hard drive? It's a
 great program, but by necessity, slow. You can create a file
 containing all the directories and files on your drive (or better yet,
 a partition) and then use WANT to search that file, rather than wait
 for FIND. Here's how to do it:

 Let's assume you have created the ASSIGN outlined above, and want to
 create a file that lists all the directories and files on your DH1:
 partition. From the CLI type this:

   list >aamyfiles:dh1contents  DH1:* lformat "%F%N" ALL

 The drive light will come on for a while. When it turns off, the file
 called dh1contents will be in the directory myfiles. Now you can use
 WANT to search dh1contents. The search time should be less than one
 second on a 1200, and longer on a 7Mhz machine. This works on CDROMs
 and floppies also.

Using an Editor instead of a filereader

 You can select an editor instead of a filereader in the Tooltypes.
 If your editor requires a stack to be set, WANT cannot do it for you.
 When the editor is called, it is passed the filename of a temporary
 file lovcated in RAM:. This file is named GAWK_OUTPUTxxxxxxxx. When
 you save your file, always SAVE AS with a different filename and path,
 or the results of your editing will be lost.

A special note to the UN*X literate

 The two text entry fields will accept ANY UN*X-like search expressions.
 Multiple expressions separated by the AND/OR gadget are allowed.
 Any expression that could be used by egrep is allowed. i.e. [AaBb],
 all logical operators, and wildcards.

   Using UN*X Regular Expressions to search for more than two terms

 Enter the expression or multiple expressions like this:

     (word1)|(word2)|(word3)  etc.

 This will find word1 OR word2 OR word3. If you click the AND OR
 gadget to AND, and enter another expression in the second text field,
 the the search will AND the two expressions.

 Since WANT is designed to shield UN*X from the user, you may
 encounted unpredictable results with multiple expressions. Grep and Gawk's
 scripts are being assembled algorithmically in realtime. This presents
 a large workload for the system. You CAN confuse the process with
 overly complex expressions.


  --------------------------------------------------------------------
                    GNU DISCLAIMER
  --------------------------------------------------------------------

             EGREP & GAWK, the powers behind WANT

    EGREP & GAWK are powerful tools written by GNU. This is part of
    GNU's disclaimer. For the rest of it, read LICENSE.

  --------------------------------------------------------------------
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

  --------------------------------------------------------------------
                    ABOUT THE AUTHORS
  --------------------------------------------------------------------

 WANT is GIFTWARE. That means if you like it and use it, you may
 send us a Gift. A birthday card or email would be nice.

    If you distribute the program, distribute the entire package.
    You may upload WANT to any BBS or archive. WANT may be freely
    distributed on club disks, by Amiga Reports and by Mr. Fred Fish.
    See below for a list of filenames to be included.

 WANT is free to use and copy as you see fit. The Authors retain all
 rights to the program. The Authors are not responsible for any
 damage the program may cause.

 WANT was tested on a 4000, 3000, 2000, 600, and a 1200  without problems.

 This is the first release of WANT. The next release will include a
 preferences section that allows you to preset groups of files to be
 searched. Predefined search terms and context lines for each group of
 files may be set. If you have any ideas about features WANT should
 include, please contact the authors. We wrote WANT so we could search
 INDEXES, RECENTS, and Fishlists, but we soon found other uses for it.
 We would really like to hear from you. If you find a character that
 causes problems with a search, please let us know.

Files included in this release (1.00):

      WANT  --------- The Executable
      egrep --------- The GNU file
      gawk ---------- The GNU file
      ixemu.library - Runtime Library for GNU utilities
      LICENSE ------- The GNU license
      WANT.guide ---- This AmigaGuide file
      WANT.doc ------ Instructions for the Guideless
      WANT.readme --- An unusually dull readme file
      Icons ---------

If you find any bugs or have any comments, please contact the Authors:

      C & UN*X Code                  Program Design, GUIs, Docs
      --------------------------     --------------------------
      Will Bow                       Colin Thompson
      1531 Corinth Unit 1            9606 Carroll Cyn. Rd. H9
      West Los Angeles, CA 90025     San Diego, CA 92126
      [phone]                 [phone]
                                     InterNet: [e-mail]

 A note to programmers:  The file requester used in want will be available
 to you as a linkable object later this fall. We are still adding features
 to it. Look in dev/c for it.

Credits

 WANT simply could not be written without including the code of many
 talented programmers who have bequeathed their work to the public domain.
 Their selfless acts of generosity allow us to continue the tradition of
 providing Free or Inexpensive Software to Amiga owners. Thanks to:

     Nico Francois for ReqTools
     Jan van deen Baard for GadToolsBox
     The GNU group for GCC 2.6.0 and all those great utilities
     Chad Randall for Iconian
     CDROM.COM for making the archives available
     Fred Fish for the same darn thing!
     Our many field testers including members of the San Diego
     Area Amiga Users Group for their invaluable ideas






  want.guide converted by
  Guide2Doc 1.0 (02-Nov-1993) FreeWare - © Koessi