
Searchtool
Version 1.0, March 18 1996

   Searchtool is a graphical user interface for several powerful commands 
   that are widely available on all Unix based systems. This document 
   serves as a comprehensive guide to the functions and services offered 
   by Searchtool.


1. Introduction

   Searchtool is a search utility for all Unix based and X Windows
   systems. The main motivation for writing the program was to create a
   tool to perform text search and replace functionalities with a more
   intuitive interface compared to the tradition command line
   interfaces. Most people who use the command line versions of these
   tools are using less than 50% of the their capabilities. With the
   right command options, these tools are extremely powerful and can be
   used to solve many problems. Unfortunately, the advance commands are
   not well advertised or documented and so only the gifted is able to
   make use of them. Searchtool will help the novice overcome this
   problem and provides the following features:

      o Searching patterns across multiple directory trees and their 
        subdirectories.

      o Caching of search results

      o Integration with emacs and Xemacs.

      o Search and replace patterns across multiple files and directory 
        trees and subdirectories.

      o Recognizing tags from the etags program to provide language
        sensitive parsing and static analyzing functions.

2. Quick Start

   2.1 Starting Searchtool

     To start Searchtool, simply type searchtool on the command line. 
     If the GNU server is not started, then a warning dialog will appear. 
     You can still perform search and replace functions using Searchtool, 
     however, you will not be able to view the files using emacs with 
     the matched pattern by simply clicking on the browser window (more 
     on this later).

   2.2 Searching for a pattern in a set of files

     The main feature of Searchtool is to search for a pattern across
     a set of files across different directory trees, including all
     subdirectories.

     To do a search, type in the pattern in the "Pattern" entry
     box. Note that by default all character are taken literally.
     ie. no regular expressions. For example, the pattern

	/* C comment */

     to search for all sections with the given C comment. The * 
     character is not interpreted as a wildcard character.

     Then type in the path to search in the "Path" entry box. The format
     for the path includes all valid directories and glob patterns
     separated by a colon ":". For example, if you want to search in the
     directories /usr/local/src and /usr/src, then enter

	/usr/local/src:/usr/src

     or to search for only C sources and headers, use

	/usr/local/src/*.[ch]:/usr/src/*.c

     You can also use relative paths and tilde notation. The relative
     paths are with respect to the directory where you invoked
     Searchtool and is also displayed in the title of the window. For
     example,

	../include:../../lib/include:~matt/src

     Once the pattern and path to search are specified, you can start a
     search by clicking on the Search button in the toolbar or selecting
     the Search option from the Entry menu. If the pattern exists within
     any of the files in the search path, then the files are displayed in
     the browser window. Otherwise, an error message is displayed in the
     status bar.

     If valid search results are returned in the browser window, you can
     selectively expand or collapse the listing by clicking on the
     expand button (blue triangle). When the list is expanded, it shows
     all the matches that was found in the particular file. You can then
     press button-2 to view the line in that file using (x)emacs. Note
     that you can still view the file using vi if the GNU server is not
     active. See section 4.x for more details.

   2.3 Searching for a pattern in a set of directories and subdirectories

     First enter the path and pattern as described in the previous section.
     Then check the "Search subdirs" checkbox to invoke searches for
     all subdirectories. Searchtool first scans through each path specified 
     in the Path entry and then recursively decent through each
     subdirectory to search the specified pattern.

   2.4 Scan Path avoidance

     When the user invokes the search function, Searchtool basically 
     performs the search in two steps. It first scans the Path entry to 
     get a list of all the files to search. The file list is then passed 
     to grep which scans through each file in turn.

     If the user specifies that the subdirectories be recursively
     traversed, this may take a long time to generate the complete file 
     list. To overcome this inefficiency, Searchtool caches the file 
     list so that they can be used for subsequent searches without having
     to scan the paths first. This assumes that the file list in each 
     directory is unlikely to change between consecutive searches. If 
     this is not the case, then the "Rescan path" checkbox can be checked
     to override this action. This is typically used if new files are 
     created in the directories between searches.

     Note that at the start of the session, this option is disabled
     and selected because the cache is initially empty. After the first
     search, this option is enabled and automatically unselected. This
     means Searchtool will only read from disk if a new directory is 
     given. Otherwise, it will use the cached listings to reduce
     searching time.

   2.5 Replacing a pattern in a set of files

     After searching for a pattern, you are given the option to replace it
     with a new pattern. Click on the Replace button in the toolbar or the
     selecting the Replace option from the Entry menu.

     A modal dialog is displayed, prompting you for the replace pattern 
     and several options. Type in the replace pattern in the 
     "Replace pattern" entry box. All characters are interpreted literally 
     unless the "Use replace metacharacters" option is checked (more in 
     the following section).

     The options and their meanings are:

        o Write changes to new files

          If this option is checked, then the replacements are written 
          to new files in the subdirectory replace.new. This gives you a 
          chance to review the changes before clobbering the existing 
          versions. Otherwise, the changes are saved on top of the 
          existing files after the file is backed up with the name
          <filename>~.

        o Interactive

          If this option is checked, each match is queried via (x)emacs. 
          This option is only available if the GNU server is active.

        o Replace words only

          Only replace pattern when it is a complete word. For example, 
          replacing pattern sym to symbol will not replace syms or mysym 
          to symbol. 

          Note that if the interactive option is used together 
          with this option, then the word boundary is different depending 
          on which (x)emacs mode you are using. For example, for a plain 
          text file, the pattern "sym" in "my_sym" is considered to be 
          a word but for a C file, it is not because the underscore is
          considered part of the word/symbol.

        o Use replace metacharacters

          Enables interpretation of special characters during replace. 
          These include an ampersand (&) and the string \#, where # is a 
          digit. The ampersand is used to replace the string matching the 
          regular expression. The \# is replaced by the n'th parenthesized 
          subexpression. The special case is \0, which replaces the 
          substring that matched the regular expression. This option is 
          only enabled if the "Regexp" option is enabled in the Preference
          dialog.

   2.6 Analyzing C-files

     The analyse function scans the C source files (files with extensions 
     .c and .h) and creates a table of C symbols. 

     To invoke this function, first enter a list of directories where you
     want Searchtool to search for C files in the "Path" entry box. Then
     select the Analyse button in the toolbar or the Analyse Path option 
     in the Entry menu. This generates a table into a hidden file named 
     .stxrf  in the current working directory. The browser window lists 
     all the C files found in the specified path.

     If you click on the expand button for each of the files in the
     browser window, you can see all the symbols in each file. By clicking 
     on the entries with Button-2, you can view the selected line in a 
     (x)emacs window.

     To see all the parsed symbols from all files, select the Symbols option
     in the View menu. This displays all the symbols found in the directory.
     If the expand button is invoked, then the files which contain the
     symbol are listed in the browser and can be viewed via (x)emacs using 
     Button-2.

     Note that is the GNU server is not active, it is possible to view
     the files using vi. See section 2.9 for more details.

   2.7 Using the History list

      All entry boxes in Searchtool contain a dropdown button which 
      displays the history list for that entry box. By clicking on the 
      button, you can select a previous entry without typing. This is 
      saved across sessions in the .searchtool file in your $HOME 
      directory.

   2.8 Showing cached search results

      All search results are cached. You can view a previous result by 
      invoking the Cache menu, which contains a dynamic list of all the 
      search commands invoked since the start of the session. You can also
      use the buttons in the tool bar to traverse the cache list.

   2.9 Setting up Preferences

      To setup the preferences, select the Preferences option in the Entry
      menu. There are three areas you can configure.

        o Current Directory

          This refers to the working directory for Searchtool. All 
          relative paths specified in the Path entry is relative to this 
          one. it also specifies the directory to save the cross reference 
          file generated from the analyse function.

        o Editor

          This options allows either the files to be viewed using vi or 
          (x)emacs with the GNU server. If vi is selected, the editor is 
          spawned in an xterm.

        o Search options

          If "Case sensitive" option is checked, then all search and replace
          patterns are case sensitive.

          If "Regexp" option is checked, then regular expression characters
          such as * . , [ ] have special meaning.

          If "Exclude backup files" is checked, then the files with 
          extensions .bak and ~ are not searched.

4. Menu Options

   The Entry menu contains actions to perform for the entry boxes and 
   contains the following options:

      Search       - start the search on the specified pattern and path
      Replace      - Invokes a dialog to replace the existing pattern with
                     a new one
      Analyse Path - Scans all C sources in the specified path and
                     generates a cross reference table
      Filter       - Not yet implemented
      Preferences  - Invoke a dialog to configure user options
      Exit         - Closes the application.

   The View menu gives operations for the browser and the general 
   appearance of the application.

      Toolbar      - If this is checked, the toolbar is displayed
      Status Bar   - The status bar is displayed if this is checked
      Expand All   - Expand all listings in the browser window
      Collapse All - Collapse all listings in the browser window
      Files        - Displays all files in the cross reference table
      Symbols      - Displays all symbols in the cross reference table

   The Cache menu gives the function to traverse through the list of 
   search results.

      Previous     - Display the previous item on the history list
      Next         - Display the next item on the history list

      This menu also contains a dynamic list of search results as the 
      user invokes the search function.

   The Help menu provides help for the user.
