\begindata{text,538490288} \textdsversion{12} \template{help} \define{global } \chapter{Gsearch: An Alternative Search Package for EZ that Works Like GNU-Emacs Search } \section{What gsearch is }\leftindent{ Gsearch is an alternative to the standard search facility in EZ and other Andrew applications. It allows you to search the text of a document for a specified pattern, and operates almost identically to the search function in the popular text-editor GNU-Emacs. The primary features of gsearch are: \leftindent{\description{1. It's incremental. This means that, as you type in the search pattern, you can see the match taking place in the text. (The standard search package requires you to enter an entire search pattern, then press \typewriter{ENTER}, before a search begins.) 2. At the end of a successful search, gsearch will place a ``mark'' at the starting location of the search. This way, you can easily jump back and forth between where you came from and where the search put you, using \typewriter{^X^X}, the swap-point-and-mark command. 3. At the end of a failing search (signified by your aborting the operation with \typewriter{^G}), gsearch returns you to the starting location of the search. }}} \section{Enabling gsearch }\leftindent{ To be able to use gsearch, you need to specify a \italic{\helptopic{keybinding}} for the two gsearch commands, ``gsearch-forward'' and ``gsearch-backward.'' Keybindings are specified in \italic{\helptopic{initfiles}}. Each Andrew application, such as EZ, uses a different initfile in your home directory. To enable gsearch in, say, EZ, you would put the following two lines in your \bold{~/.ezinit} file: \example{addkey gsearch-forward ^S textview addkey gsearch-backward ^R textview } This would cause the two functions to be bound to the keys \typewriter{^S} and \typewriter{^R}, which are the bindings that most people use. You may choose whatever bindings you like. Some people have a file called \bold{~/.atkinit} which is \italic{included} by all their other initfiles. If you put the above \typewriter{addkey} commands in \bold{~/.atkinit}, then gsearch will be enabled in all Andrew applications. } \section{Using gsearch }\leftindent{ You begin a search by invoking either gsearch-forward or gsearch-backward, usually by pressing \typewriter{^S} or \typewriter{^R}. You are then prompted with an empty \italic{search pattern}. Typing ordinary characters will place them in the search pattern. Any time the search pattern changes, the best match for the current pattern is found and displayed in the text by highlighting it. If no appropriate match is found, you are placed in a \italic{failing} search (note that you're still in a search even if it is, at the moment, failing). If the search is presently failing, pressing \typewriter{^G} will restore you to the last state in which the search was \italic{succeeding}. If the search is presently succeeding, then pressing \typewriter{^G} will abort the operation altogether and return you to where you were before you started the search. \typewriter{^S} and \typewriter{^R} are the ``search-again'' keys. If the search is presently succeeding, then search-again will look for the next occurrence of the current pattern. If the search is presently failing, search-again will \italic{wrap around} the end of the document and look for another occurrence starting at the other end. \typewriter{^S}, which is ``search-again-forward,'' will cause the search to wrap around the bottom of the document and search forward from the top; \typewriter{^R}, which is ``search-again-backward,'' will cause the search to wrap around the top of the document and search backward from the bottom. If you use search-again in the opposite direction of the current search, then the search direction will be reversed. \typewriter{^S} and \typewriter{^R} can also be used at the beginning of a search to choose the default pattern, if one is offered. The default pattern is the most recent succeeding pattern from a previous search. If a default is available, it will be shown in square brackets when the search begins. Use \typewriter{^S} or \typewriter{^R} to indicate that you want to use the default. The \typewriter{ESC} key is used to indicate successful termination of a search. When \typewriter{ESC} is pressed, the search terminates in the current location, and the current pattern is stored to be used again later as a default pattern. Also, a \italic{mark} is placed in the location where you were before the search began. This allows you to use \typewriter{^X^X}, the swap-point-and-mark command, to jump back and forth between where you were and where the search put you. \typewriter{^Q} is used to ``quote'' a character. Use it when you need to place a character in the search pattern which would normally be interpreted as a gsearch command. For instance, typing \typewriter{^Q^S} would place a ``^S'' in the search pattern without invoking ``search-again.'' \typewriter{^W} is used to place the currently-selected text in the document onto the end of the search pattern. \typewriter{^Y} will yank the contents of the cut buffer onto the end of the search pattern. The \typewriter{BACKSPACE} or \typewriter{DELETE} key can be used to erase characters from the end of the search pattern, but this isn't precisely how it works. What actually happens is that, with each press of \typewriter{BACKSPACE} or \typewriter{DELETE}, you are taken one step backwards through the history of the search. Thus, it's possible to press \typewriter{BACKSPACE} or \typewriter{DELETE} and not have any characters erased from the search pattern. Here's an example (\underline{underlining} is used to indicate text that is selected): \leftindent{Your document consists of the text \leftindent{\typewriter{xyz xyz}} }\leftindent{The text caret is at the beginning of the document, before the first \typewriter{x}. You invoke a forward search and type \typewriter{x} at the prompt. The search pattern is now the string ``x,'' and this is what it matches: }\leftindent{\typewriter{\leftindent{\underline{x}yz xyz}} }\leftindent{Next you type a \typewriter{y}, making the pattern ``xy.'' } \leftindent{\typewriter{\leftindent{\underline{xy}z xyz }}Next you type a z:\typewriter{\leftindent{ \underline{xyz} xyz }}Now you hit \typewriter{^S} to ``search-again-forward,'' and you match\typewriter{\leftindent{ xyz \underline{xyz }}}Now suppose you use \typewriter{BACKSPACE} or \typewriter{DELETE}. You will back up to the previous state you were in, which in this case does not include erasing any characters. After pressing \typewriter{BACKSPACE} or \typewriter{DELETE}, you will see \leftindent{\typewriter{\underline{xyz} xyz}} since this was your previous state. If you press \typewriter{BACKSPACE} or \typewriter{DELETE} a second time, you will be returned to the state before this one, in which the pattern was ``xy'' (\italic{now} you've managed to erase that ``z'') and the match was \leftindent{\typewriter{\underline{xy}z xyz}} So, \typewriter{BACKSPACE} or \typewriter{DELETE} works by backing up over previous states, not necessarily by backing up over previous characters.} \typewriter{^L} can be used at any time to redraw the window. If a character not recognized by gsearch is typed in, then that character is assumed to be some other command. Gsearch will exit as if \typewriter{ESC} had been pressed (i.e., it will leave you where you are, and will place a mark where you came from) and will execute the new keystroke. For instance, if \typewriter{^F} is typed during a search, then the search will terminate successfully in the current location, and then \typewriter{^F}, the move-forward-by-one-character command, will be executed. At all times, the message line at the bottom of the window indicates the current state of gsearch (backward or forward, failing or succeeding, wrapped or not) and what the current pattern looks like. }\section{Quick reference }\leftindent{ \description{\typewriter{^S} Search-again-forward. Also used to select the default pattern, if one is provided. Will reverse the direction of a backward search. In a failing forward search, will wrap around the end of the document. \typewriter{^R} Search-again-backward. Also used to select the default pattern, if one is provided. Will reverse the direction of a forward search. In a failing reverse search, will wrap around the beginning of the document. \typewriter{^Q} Quote the next character. Used to add unusual characters to the search pattern. \typewriter{BACKSPACE} or \typewriter{DELETE} Back up through previous states of the search. Can loosely be thought of as erasing the end of the search pattern. \typewriter{^G} Abort. In a failing search, returns to the most recent succeeding state. Otherwise, aborts the search altogether and returns to the pre-search location. \typewriter{ESC} Exit. Terminates the search in the current location, places a mark in the pre-search location, and saves the succeeding pattern to be offered as a default in the next search. \typewriter{^W} Add selection to pattern. Used to take the currently-displayed selection and place it on the end of the search pattern. \typewriter{^Y} Yank. Used to place the contents of the cut buffer on the end of the search pattern. \typewriter{^L} Redraw. Redraws the window at any time. \italic{printing characters} Printing characters add themselves to the end of the search pattern. This includes whitespace characters, which also include things like newline and tab. \italic{anything else} Any other characters typed in are taken to be a new editing command. The search is exited as if \typewriter{ESC} had been pressed, and then the new keystroke is executed. }} \section{Program Author} \leftindent{ Bob Glickstein, Information Technology Center} \section{Related tools} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" from the pop-up menu to see the help file for: \leftindent{\italic{\helptopic{search} \helptopic{initfiles} \helptopic{ez-keys}}} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,828,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538490288}