<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="chm.search" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>The Full Text Search</title>

  <para>
   This edition of the PHP Manual includes an advanced full text
   search possibility provided by the viewer application. This enables
   users to search through every word in the help file to find a
   match. For example, if a user does a full-text search on the word
   "Apache", every topic that contains the word "Apache" will be listed. 
   Advanced full-text search allows a user to search using boolean,
   wildcard, and nested expressions. A user can also limit the search
   to previous results, match similar words, or search topic titles only.
  </para>
  
  <para>
   The usage of the search feature is fairly straightforward. Click on
   the search tab, type in the desired words and press ENTER (or click
   on "List Topics"). Then you'll receive a list of matches from the
   PHP Manual (and the notes). You can use the button with a right
   arrow on it to add boolean operators to your search (or you can type
   them in). As you see the results, you can use the column headings
   (Title, Location and Rank) to sort the topic list. The default order
   is by Rank. You can also adjust some parameters at the bottom of this
   tab.
  </para>

  <para>
   The words found are highlighted on the current page in the Topic pane
   by default. You can turn off this feature by choosing the "Search
   Highlight Off" menu item in the Options menu. To can get this feature
   back similarly. If you are viewing a long topic, only the first 500
   instances of a search word or phrase will be highlighted, due to a
   limitation of the viewer. 
  </para>

  <sect1 xml:id="chm.search.rules">
   <title>General searching rules</title>
   <para>
    A basic search consists of the word or phrase you want to find. You
    can use wildcard expressions, nested expressions, boolean operators,
    similar word matches, a previous results list, or topic titles to further
    define your search.
   </para>
   <para>
    The basic rules for formulating queries are as follows: 
    <itemizedlist>
     <listitem>
      <simpara>Searches are not case-sensitive, so you can type your search in uppercase or lowercase characters.</simpara>
     </listitem>
     <listitem>
      <simpara>
       You may search for any combination of letters (a-z) and numbers (0-9).
       You cannot search for single letters (a, b, c, etc.) and common
       words, like: an, and, as, at, be, but, by, do, for, from, have, he,
       in, it, not, of, on, or, she, that, the, there, they, this, to, we,
       which, with, you. 
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Punctuation marks such as the period (.), colon (:), semicolon (;), comma (,),
       and hyphen (-) are ignored during a search. 
      </simpara>
     </listitem>
     <listitem>
      <simpara>Group the elements of your search using double quotes or parentheses to set apart each element. You cannot search for quotation marks.</simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    <note>
     <para>
      If you are searching for a file name with an extension, you should group
      the entire string in double quotes, ("filename.ext"). Otherwise, the period
      will break the file name into two separate terms. The default operation
      between terms is AND, so you will create the logical equivalent to
      "filename AND ext."
     </para>
    </note>
   </para>
  </sect1>
  
  <sect1 xml:id="chm.search.words">
   <title>Searching for words or phrases</title>
   <para>
    You can search for words or phrases and use wildcard expressions.
    Wildcard expressions allow you to search for one or more characters
    using a question mark or asterisk. The table below describes the
    results of these different kinds of searches.
    <table>
     <title>Word and phrase searches</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Search for</entry>
        <entry>Example</entry>
        <entry>Results</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>A single word</entry>
        <entry>select</entry>
        <entry>Topics that contain the word "select". (You will also find its grammatical variations, such as "selector" and "selection".)</entry>
       </row>
       <row>
        <entry>A phrase</entry>
        <entry>"new operator" or new operator</entry>
        <entry>
         <simpara>
          Topics that contain the literal phrase "new operator" and all its grammatical variations.
         </simpara>
         <simpara>
          Without the quotation marks, the query is equivalent to specifying "new AND operator," which
          will find topics containing both of the individual words, instead of the phrase.
         </simpara>
        </entry>
       </row>
       <row>
        <entry>Wildcard expressions</entry>
        <entry>esc* or HT??</entry>
        <entry>
         <simpara>
          Results for the first example include topics that contain the terms "ESC",
          "escape", "escalation", and so on. The asterisk cannot be the only
          character in the term.
         </simpara>
         <simpara>
          Results for the second example include topics that contain the terms "HTTP",
          "HTML" and so on. The question mark cannot be the only character in the
          term.
         </simpara>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    <note>
     <para>
      Select the Match similar words check box to include minor grammatical variations
      for the phrase you search. This feature only locates variations of the word with
      common suffixes. For example, a search on the word "add" will find "added," but
      it will not find "additive". This option is independent of other options or syntax.
      If you do a titles-only search, variations in titles will be matched. If you use
      quotes (or any other query operator) any variation of the word can appear; for
      example, "stemmed search" will also match "stemming search".
     </para>
    </note>
   </para>
  </sect1>
  
  <sect1 xml:id="chm.search.terms">
   <title>Defining search terms</title>
   <para>
    The AND, OR, NOT, and NEAR operators enable you to precisely define your
    search by creating a relationship between search terms. The following table
    shows how you can use each of these operators. If no operator is specified,
    AND is used. For example, the query "server cgi security" is equivalent
    to "server AND cgi AND security".
    <table>
     <title>Search operators</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Search for</entry>
        <entry>Example</entry>
        <entry>Results</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>Both terms in the same topic</entry>
        <entry>http AND apache</entry>
        <entry>Topics containing both the words "http" and "apache".</entry>
       </row>
       <row>
        <entry>Either term in a topic</entry>
        <entry>ming OR swflib</entry>
        <entry>Topics containing either the word "ming" or the word "swflib" or both.</entry>
       </row>
       <row>
        <entry>The first term without the second term</entry>
        <entry>xml NOT expat</entry>
        <entry>Topics containing the word "xml" but not the word "expat".</entry>
       </row>
       <row>
        <entry>Both terms in the same topic, close together</entry>
        <entry>database NEAR security</entry>
        <entry>Topics containing the word "database" within eight words of the word "security".</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    <note>
     <para>
      The |, &amp;, and ! characters can also be used in place of OR AND and
      NOT respectively. This may not work if you use a very old version of the
      viewer.
     </para>
    </note>
   </para>
  </sect1>

  <sect1 xml:id="chm.search.nested">
   <title>Using nested expressions when searching</title>
   <para>
    Nested expressions allow you to create complex searches for information.
    For example, "html AND ((smtp OR pop3) NEAR mail)" finds topics
    containing the word "html" along with the words "smtp" and "mail"
    close together, or containing "html" along with the words "pop3" and
    "mail" close together.
   </para>
   <para>
    The basic rules for searching help topics using nested expressions are
    as follows:
    <itemizedlist>
     <listitem>
      <simpara>
       You can use parentheses to nest expressions within a query. The
       expressions in parentheses are evaluated before the rest of the query.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       If a query does not contain a nested expression, it is evaluated from left to right.
       For example: "mail NOT pop3 OR smtp" finds topics containing the word "mail" without
       the word "pop3" or topics containing the word "smtp". On the other hand, "mail NOT
       (pop3 OR smtp)" finds topics containing the word "mail" without either of the words
       "pop3" or "smtp".
      </simpara>
     </listitem>
     <listitem>
      <simpara>You cannot nest expressions more than five levels deep.</simpara>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>
  <!--
  <sect1 xml:id="chm.search.notes">
   <title>Manual Content and User Note Separation</title>
   <para>
    The manual content and the user notes are separated to
    <filename>php_manual_LANG.chm</filename> and
    <filename>php_manual_notes.chm</filename>. There were several reasons
    to do this, including:
    <itemizedlist>
     <listitem>
      <simpara>
       This way you can update the user notes and the manual independently
       as you need.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       You can have more than one language of the manual, while only
       need to have one notes file. All the CHM files need to be in the
       same directory, and all translations need to share the same
       preferences if you would not like to have more then one notes file.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       You can bookmark manual pages with notes, or just a notes part
       of a page separately.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       You can "turn off" user note display and user note search results by
       simply deleting <filename>php_manual_notes.chm</filename>, moving it
       out of the directory or renaming it.
      </simpara>
     </listitem>
    </itemizedlist>
    All these benefits lead us to provide the manual the way you can see it
    right now. This distribution had the effect on the full text search that
    you get search results from the manual content and from the user notes
    as separate ones. The "Location" column shows the source of the result,
    also enabling you to "add precedence" to manual content results with
    ordering the results by "Location". User note page titles are also
    prefixed with "N:" to make them easily distinguishable in the favorites
    list (there's no location info in the favorites list).
   </para>
  </sect1>
  -->
  
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->