\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}
