php-doc-en/chmonly/search.xml
Christoph Michael Becker dcd5448282 Fix other typos outside of php module docs
Patch provided by tandre@php.net.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@349711 c90b9560-bf6c-de11-be94-00142212c4b1
2020-04-27 06:59:43 +00:00

314 lines
12 KiB
XML

<?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
-->