path: root/help/C/search.xml

<!-- ============= Search  ============--> 

	<sect2 id="xiphos-searchpane">
		<title>Simple Searches</title>
		<para>
		To conduct a quick search within the current Bible or commentary module, the Search Bar in the Sidebar should usually be adequate. Click either
		in the menu bar <guimenuitem>Edit-&gt;Search</guimenuitem> or in the Sidebar <guimenuitem>Modules-&gt;Search</guimenuitem> to access it.
		</para> 
	
		<figure>
		<title>The Search Bar</title>
                       <screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/interface_searchpane.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/interface_searchpane.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>The Search Bar</phrase> 
	    </textobject> 
	  </mediaobject> 
	
                       </screenshot>

                </figure>
              <para>
		The <interface>Search Dialog</interface> consists of the following parts:
		</para>
			<itemizedlist>
				<listitem>
					<para>
					Search Key Entry box
					</para>
				</listitem>
				<listitem>
					<para>
					Search Module Selector
					</para>
				</listitem>
				<listitem>
					<para>
					Search Type Selector
					</para>
				</listitem>
				<listitem>
					<para>
					Search Options Checkbox
					</para>
				</listitem>
				<listitem>
					<para>
					Search Scope Selector
					</para>
				</listitem>
				<listitem>
					<para>
					Search Results View
					</para>
				</listitem>
			</itemizedlist>			
		<sect3 id="xiphos-search-key">
			<title>Search Key Entry Box</title>
			<para>Allows entry of the key for which you would like to search. The 
			search key can be a word, part of a word, several words, a phrase, or 
			a regular expression depending on the type of search selected. When 
			the search key is entered and all other selections in the search dialog 
			are complete, click the <guibutton>Find</guibutton> button to begin 
			the search.
			</para>
			<para>
			This search uses the optimized search method (see next section) if
			the module has previously been indexed, and will use AND semantics by default 
			(verses must contain all words you entered).
			</para>
			</sect3>
		
		<sect3 id="xiphos-search-modselect">
			<title>Search Module Selector</title>
			<para>Allows selection of which modules	you would like to search. 
			Select <guibutton>Bible</guibutton> to search Bible versions or 
			<guibutton>Commentary</guibutton> to search commentaries. Only 
			the currently active module will be searched.</para>
		</sect3>
		
		<sect3 id="xiphos-search-typeselect">
		<title>Search Type Selector</title>
		<para>Allows selection of the type of search. There are three search
		types available:
		</para>
			<variablelist>
				<varlistentry>
					<term><guibutton>Multi word</guibutton></term> 
					<listitem><para>This type will match any verse that has 
					all the words in the search key, regardless of where 
					they appear in the verse.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><guibutton>Regular expression</guibutton></term> 
					<listitem><para>This search uses a regular expression
					as a search key. A regular expression is a pattern used 
					to match a string of text. A regular expression can be 
					used to find verses with words that match a particular 
					pattern. For example the regular expression
					<userinput>[a-z]*iah </userinput> will match verses that contain
					the words Aiah, Ahaziah, Athaliah and Amariah.</para>
					<para>A complete discussion of regular expressions is 
					beyond the scope of this manual, but more information 
					can be found in the grep man page.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><guibutton>Exact phrase</guibutton></term> 
					<listitem><para>This type will match the search key
					exatly as entered. If the search key is <userinput>
					it is good</userinput>, this search would match a verse
					which contains "<emphasis>it is good</emphasis>," but 
					would not match a verse	which contains "<emphasis>
					good</emphasis>, and doeth <emphasis>it</emphasis> not, 
					to him it <emphasis>is</emphasis> sin."</para></listitem>
				</varlistentry>
			</variablelist>
 		</sect3>

		<sect3 id="xiphos-search-options">
			<title>Search Options Checkbox</title>
			<para>Allows selecting of search options. The only available option 
			is <guibutton>Match case</guibutton>. Check this box to make the 
			search case sensitive.</para>
		</sect3>
		
		<sect3 id="xiphos-search-scopeselect">
			<title>Search Scope Selector</title>
			<para>Allows defining the range within the specificed module that will
			be searched. There are three search scopes available:</para>
			<variablelist>
				<varlistentry>
					<term><guibutton>No scope</guibutton></term>
					<listitem><para>This button causes the search to
					to include the entire module.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guibutton>Use bounds</guibutton></term>
					<listitem><para>Selecting this button produces two dropdown
					selector boxes marked <guilabel>Lower</guilabel> and
					<guilabel>Upper</guilabel>. Select the first book
					to search in the <guilabel>Lower</guilabel> box and
					the last book to search in the <guilabel>Upper</guilabel>
					box. The search will begin with the <guilabel>Lower
					</guilabel> book and end with the <guilabel>Upper
					</guilabel> book and include all books in between.
					</para>
					<para>Chapter and verse numbers can be entered into
					the search bound boxes as well to further narrow the
					search. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guibutton>Last search</guibutton></term>
					<listitem><para>Select this button to do a new 
					search including only the verses returned as a 
					result of the last search. Use this with a new 
					search key to narrow the search further.</para>
					</listitem>
				</varlistentry>
			</variablelist> 
		</sect3>
		<sect3 id="xiphos-search-results">
			<title>Search Results View</title>
			<para>This shows a list of the current search results for previewing, navigation, or saving.</para>
			<variablelist>
				<varlistentry>
					<term>Preview</term>
					<listitem><para>To preview the search result, simply click on an individual result.
					The entry will show in the preview pane.
					</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Navigation</term>
					<listitem><para>Navigation to the search result can be done in two ways. To open the result
					in a new tab, middle-click the mouse. To open the result in the current tab, double-click the result.
					</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Save Results</term>
					<listitem><para>You may save your results as a list of bookmarks. To do this, right-click and select
					<guilabel>Save List</guilabel>. You will be prompted to enter a name for the folder that your results
					will be saved to. After you have saved the results, you may view them by going to your bookmarks and
					finding the folder you just named.
					</para>
					</listitem>
				</varlistentry>
			</variablelist>
	</sect3>
	</sect2>
	<sect2 id="xiphos-advanced-search">
	   <title>Advanced Searches</title> 
	   <para>
		More complicated searches might require the use of the advanced search functions, found under <guimenuitem>Edit-&gt;Advanced
		Search</guimenuitem>.
	   </para>
	 
	  <figure>
	  <title>The Advanced Search Dialogue</title>
	  <screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/search_search.png" format="PNG" /> 
	    </imageobject>
	    <!-- EPS versions of the figures are not required at the moment. -->
            <!-- 
		    <imageobject>
      		<imagedata fileref="figures/search_search.eps" format="EPS"/>
    		    </imageobject>
	    -->
	    <textobject> 
	      <phrase>The Advanced Search  Dialog</phrase> 
	    </textobject> 
	  </mediaobject> 
	
          </screenshot>	

          </figure>
           
	   <para>
		In <guimenuitem>Advanced Search</guimenuitem>, much more complex queries can be constructed, involving custom search ranges,
		custom lists of modules over which to search, regular expression matching (see next section), and attribute-based searches
		such as are found in footnotes or Strong's Hebrew and Greek dictionary references.
	   </para>

	   <para>
		The default search is multi-word, a somewhat slow and blunt search through module text.  Also available is an optimized
		search based on the Lucene indexing and search library. In order to use the optimized search, the index must be constructed
		beforehand: Please see the preceding section on the Module Manager regarding the Maintenance functions, including indexing. A
		web search will provide several references to the syntax needed to put to use the power of optimized Lucene search. A few
		examples follow:
	   </para>
	   
	   <para>
		Simple Searches: just type in the words you want to search for. To return only verses that include all of the words,
		prefix the word with "+". So, in the KJV, you could find Psalm 23 by searching for "+Lord +shepherd +want". To search for
		an entire phrase, surround the entire phrase with quotes, like "maketh me to lie down" (note that quotes are unnecessary
		in all of the other examples).
	   </para>
	   
	   <para>
		Single Letter Wildcard: to search for "veil" or "vail", use this syntax "v?il". The "?" represents a single character
		that could be anything. A more complex example returns both spellings for Isaiah used in the KJV. "?saia?" will return
		results for "Isaiah" and "Esaias".
	   </para>

	   <para>
		Multiple Letter Wildcard: to search for "prophet" or "prophesy" or "prophecy" or "prophesied", use this syntax "prophe*".
	   </para>

	  <para>
		AND syntax: in the advanced search to return results for all of the search terms, you must put "AND" in between the terms.
		To continue our example, if we wish to search for any occurrence of Isaiah or Esaias that also mention either prophet, or
		prophecy, or prophesy, we can do a search like this: "?saia? AND prophe*". 
	  </para>

	   <para>
		By default, two standard search ranges are defined, for Old and New Testament; you may wish to define others for
		e.g. "Gospels" or "Paul's Epistles". One custom module list containing only the first Bible found will be present.
		If desired, new searches can be performed across only the current results of the previous search.  Any modules may be
		searched, including general books and even dictionaries, in any combination.
	   </para>

	   <para>
		Note the tooltip in the screenshot above, for Attributes search.  This qualifier is used to perform searches on attributes
		that are carried with verses, instead of verse content proper, such as footnote content or Strong's Hebrew and Greek
		references.  If this button is selected, specific attribute qualifiers must be made in the Attribute Search tab, at the
		right end of the tab set.  Strong's references are identified with a leading "H" or "G" and the numeric Strong's identifier.
		Thus, a search of KJV for Strong's Greek #140, using "G140", will return the single result of Matthew 12:18.
	   </para>
		
	   <para>
		If you have indexed your modules, there is a much faster way to search for Strong's references. Enter your search preceded by 
		"lemma:", so to search for Strong's Greek #140, enter "lemma:G140". You must have selected <guibutton>Optimized ("Lucene")</guibutton>
		for this to work.
	  </para>

	   <para>
		The "Find" button also stops an in-progress search, as its tooltip indicates.
	   </para>

	   <para>
		Results will show in the <guibutton>Results</guibutton> tab. If you wish to show Strongs, Morphology, or Footnote tags,
		make those selections on the <guibutton>Attributes Search</guibutton> tab. Clicking once on the result will show the result
		in the <guibutton>Advanced Search</guibutton> previewer. Hovering over Strongs, Morphology, Footnote, or Cross-reference
		tags will show the results in the main previewer. Double-clicking a result will cause the current tab to navigate to that
		result. This applies to search results in general books and commentaries as well, but note that the respective tab must
		be visible.
	   </para>

	   <warning>
	   	<para>
		 Changes to some of the settings (e.g. scope of search, searched modules, etc.) in Advanced Search will 	affect the simple search via the side pane but not vice versa.
		</para>
	   </warning>  
	   </sect2>

	<sect2 id="hdbk-op-search-dialog-text-regexp">
		<title>Search Syntax using Regular Expression</title>

		<para>
			Regular expression searches provide a way to do simple or complex searches for strings that match a pattern or set of patterns (branches) separated by vertical bars &quot;|&quot;. While a pattern can be built to look for a word or phrase, a simple pattern that consists of a word does not look for only that word but for any place the string of letters that make that word are found. A search for &quot;right&quot; will return verses that contain the word &quot;right&quot;, but also &quot;<emphasis>right</emphasis>eous&quot;, &quot;<emphasis>right</emphasis>eousness&quot;, &quot;un<emphasis>right</emphasis>eous&quot;, &quot;up<emphasis>right</emphasis>&quot; and even &quot;b<emphasis>right</emphasis>&quot;. A search for &quot;hall not&quot; is not a search for &quot;hall&quot; AND &quot;not&quot; but for the string &quot;hall not&quot; with a space between the second &quot;l&quot; and the &quot;n&quot;. The search for &quot;hall not&quot; will find occurrences of &quot;s<emphasis>hall not</emphasis>&quot;.
		</para>
		<para>
			The power of Regular Expressions is in the patterns (or templates) used to define a search. A pattern consists of
ordinary characters and some special characters that are used and interpreted by a set of rules. Special characters include
.\[^*$?+. Ordinary (or simple) characters are any characters that are not special. The backslash, &quot;\&quot;, is used to convert special characters to ordinary and ordinary characters to special.
		 </para>
		<para>
			Example: the pattern &quot;<emphasis>i. love\.</emphasis>&quot; will find sentences that end with &quot;h<emphasis>i</emphasis>s <emphasis>love</emphasis>&quot; or &quot;<emphasis>i</emphasis>n <emphasis>love</emphasis>&quot; or &quot;<emphasis>i</emphasis>s <emphasis>love</emphasis>&quot; followed by
a period. The first period in &quot;i. love\.&quot; is a special character that means allow any character in this position. The
backslash in &quot;i. love\.&quot; means that the period following it is not to be considered a special character, but is
an ordinary period. 
		</para>

		<sect3 id="hdbk-op-search-dialog-text-regexp-rules">
			<title>Rules for Regular Expression Search Requests</title>
			<itemizedlist>
<listitem><para>. The period matches any character.</para></listitem>
<listitem><para>* The asterisk matches 0 or more characters of the
	preceding: set, character or indicated character.</para></listitem>
<listitem><para>+ The plus sign matches 1 or more characters of the
	preceding: set, character or indicated character.</para></listitem>
<listitem><para>? The question mark matches 0 or 1 character of the
	preceding: set, character or indicated character.</para></listitem>
<listitem><para>[ ] Square brackets match any one of the characters
	specified inside [ ].</para></listitem>
<listitem><para>^ A caret as the first character inside [ ] means NOT.</para></listitem>
<listitem><para>^ A caret beginning a pattern anchors the beginning of a
	line.</para></listitem>
<listitem><para>$ A dollar at the end of a pattern anchors the end of a
	line.</para></listitem>
<listitem><para>| A vertical bar means logical OR.</para></listitem>
<listitem><para>( ) Parentheses enclose expressions for grouping.
<emphasis>Not supported!</emphasis></para></listitem>
<listitem><para>\ A backslash can be used prior to any special character
	to match that character.</para></listitem>
<listitem><para>\ A backslash can be used prior to an ordinary character
	to make it a special character.</para></listitem>
</itemizedlist>

<sect4 id="period">
<title>The Period</title>

<para>The Period &quot;.&quot; will match any single character even
a space or other non-alphabet character.
<emphasis>s.t</emphasis> matches <emphasis>s</emphasis>i<emphasis>t</emphasis>,
<emphasis>s</emphasis>e<emphasis>t</emphasis>,<emphasis> s</emphasis>o<emphasis>t</emphasis>,
etc., which could be located in <emphasis>s</emphasis>i<emphasis>t</emphasis>ting,
compas<emphasis>s</emphasis>e<emphasis>t</emphasis>h and <emphasis>s</emphasis>o<emphasis>t</emphasis>tish
<emphasis>b..t</emphasis> matches <emphasis>b</emphasis>oo<emphasis>t</emphasis>,
<emphasis>b</emphasis>oa<emphasis>t</emphasis> and <emphasis>b</emphasis>ea<emphasis>t
foot.tool </emphasis>matches <emphasis>foot</emphasis>s<emphasis>tool </emphasis>and
<emphasis>foot tool</emphasis></para>
</sect4>


<sect4 id="asterisk">
<title>The Asterisk</title>

<para>The asterisk &quot;*&quot; matches zero or more characters of the preceding:
set, character or indicated character. Using
a period asterisk combination &quot;.*&quot; after a commonly
found pattern can cause the search to take a very long time,
making the program seem to freeze.
<emphasis>be*n</emphasis> matches<emphasis> beeen, been, ben</emphasis>,
and <emphasis>bn</emphasis> which could locate Reu<emphasis>ben</emphasis>
and She<emphasis>bn</emphasis>a.</para>
</sect4>


<sect4 id="plus">
<title>The Plus Sign</title>
<para>The Plus Sign &quot;+&quot; matches one or more characters of the preceding:
set, character or indicated character. Using
a period and plus sign combination &quot;.+&quot; after a
commonly found pattern can cause the search to take a very long
time, making the program seem to freeze.
<emphasis>be+n</emphasis> matches <emphasis>beeen, been</emphasis> and <emphasis>ben</emphasis>,
but not <emphasis>bn</emphasis>.</para>
</sect4>


<sect4 id="question">
<title>The Question Mark</title>
<para>The Question Mark &quot;?&quot;matches zero or one character of the
preceding: set, character or indicated character.
<emphasis>be?n</emphasis> matches <emphasis>ben</emphasis> and <emphasis>bn</emphasis>
but not <emphasis>been</emphasis>.
<emphasis>trees?</emphasis> matches <emphasis>trees</emphasis> or <emphasis>tree</emphasis>.</para>
</sect4>


<sect4 id="bracket">
<title>The Square Brackets </title>
<para>The Square Brackets &quot;[]&quot; enclose a set of characters that can
match. The period, asterisk, plus sign and question mark are not
special inside the brackets. A minus sign can be used to indicate
a range. If you want a caret &quot;^&quot; to be part of the
range do not place it first after the left bracket or it will be
a special character. To include a &quot;]&quot; in the set make
it the first (or second after a special &quot;^&quot;) character
in the set. To include a minus sign in the set make it the first
(or second after a special &quot;^&quot;) or last character in
the set.
<emphasis>s[eia]t</emphasis> matches <emphasis>set</emphasis>, <emphasis>sit</emphasis>,
and <emphasis>sat</emphasis>, but not <emphasis>s</emphasis>o<emphasis>t</emphasis>.
<emphasis>s[eia]+t </emphasis>matches as above but also, <emphasis>seat,
seet, siet</emphasis>, etc.
<emphasis>[a-d]</emphasis> matches <emphasis>a, b, c,</emphasis> or <emphasis>d</emphasis>.
<emphasis>[A-Z]</emphasis> matches any uppercase letter.
[.;:?!] matches ., ;, :, ?, or ! but not a comma.
[ ]^-] matches ] or ^ or -</para>
</sect4>


<sect4 id="caret">
<title>The Caret first in Square Brackets </title>
<para>If the Caret is the first character after the left bracket (&quot;[^&quot;) it
means NOT.
<emphasis>s[^io]t</emphasis> matches <emphasis>set, sat</emphasis>, etc.,
but not <emphasis>s</emphasis>i<emphasis>t</emphasis> and <emphasis>s</emphasis>o<emphasis>t</emphasis>.</para>
</sect4>

<sect4 id="caret-s">
<title>The Caret as Start of Line Anchor </title>
<para>If the Caret is the first character in a pattern (&quot;^xxx&quot;) it anchors
the pattern to the start of a line. Any match must be at the
beginning of a line. Because of unfiltered
formatting characters in some texts, this feature does not always
work, but may if a few periods are placed after the caret to
account for the formatting characters.
<emphasis>^In the beginning</emphasis> matches lines that
start with &quot;<emphasis>In the beginning</emphasis>&quot;.
(May need to use: <emphasis>^.....In the beginning</emphasis>)</para>
</sect4>


<sect4 id="dollar">
<title>The Dollar Sign as End of Line Anchor </title>
<para>If the Dollar Sign is the last character (&quot;xxx$&quot;) in a pattern it
anchors the pattern to the end of a line. Any match must be at
the end of a line. Because of unfiltered
formatting characters in some texts, this feature does not always
work, but may if a few periods are placed before the dollar sign
to account for the formatting characters.
<emphasis>Amen\.$</emphasis> matches lines that end with
&quot;<emphasis>Amen.</emphasis>&quot; (May
need to use Amen\....$, Amen\..........$, or even
Amen\....................$)</para>
</sect4>


<sect4 id="bar">
<title>The Vertical Bar </title>
<para>The Vertical Bar &quot;|&quot; between patterns means OR.
<emphasis>John|Peter</emphasis> matches <emphasis>John</emphasis> or <emphasis>Peter.
John .*Peter|Peter .*John</emphasis> matches <emphasis>John</emphasis>
... <emphasis>Peter</emphasis> or <emphasis>Peter</emphasis> ... <emphasis>John</emphasis>.
(.* slows a search)
<emphasis>pain|suffering|sorrow</emphasis> matches <emphasis>pain</emphasis>,
or <emphasis>suffering</emphasis>, or <emphasis>sorrow</emphasis>.</para>
</sect4>


<sect4 id="parenth">
<title>The Parentheses</title>
<para><emphasis>The use of Parentheses &quot;( )&quot; is
not supported!</emphasis></para>
</sect4>


<sect4 id="backslash">
<title>The Backslash Prior to a Special Character</title>
<para>The Backslash prior to a special character (&quot;\*&quot;) indicates that the
character is not being used in its special meaning, but is just
to match itself.
<emphasis>amen\.</emphasis> matches <emphasis>amen.</emphasis> but not <emphasis>amen</emphasis>t
and will not locate firm<emphasis>amen</emphasis>t.</para>
</sect4>

<sect4 id="backslash-o">
<title>The Backslash Prior to an Ordinary Character </title>

<para>The Backslash prior to an ordinary character (&quot;\o&quot;) indicates that
the character is not being used to match itself, but has special
meaning.</para>

<itemizedlist>
<listitem><para>
\b if use outside [ ] means word boundary. If used inside [ ] means backspace.
<emphasis>\brighteous\b</emphasis> matches <emphasis>righteous</emphasis> but
not un<emphasis>righteous</emphasis> or <emphasis>righteous</emphasis>ness</para></listitem>
<listitem><para>\B means non-word boundary.  <emphasis>\Brighteous\B</emphasis>
matches un<emphasis>righteous</emphasis>ness and un<emphasis>righteous</emphasis>ly
but not <emphasis>righteous</emphasis>, un<emphasis>righteous</emphasis> or <emphasis>
righteous</emphasis>ness.</para></listitem>
<listitem><para>\d means digit; same as [0-9].</para></listitem>
<listitem><para>\D means non-digit, same as [^0-9].</para></listitem>
<listitem><para>\s means space. </para></listitem>
<listitem><para>\S means not a space. </para></listitem>
<listitem><para>\w means alphanumeric; same as [a-zA-Z0-9_].</para></listitem>
<listitem><para>\W means not alphanumeric; same as [^a-zA-Z0-9_].</para></listitem>
</itemizedlist>
</sect4>
</sect3>
</sect2>