File: search.html

package info (click to toggle)
wn 2.0.5-3
links: PTS
area: main
in suites: slink
size: 2,208 kB
ctags: 1,499
sloc: ansic: 14,439; sh: 2,430; perl: 1,360; makefile: 291
file content (558 lines) | stat: -rw-r--r-- 21,359 bytes
<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN">
<html>
  <head>
    <title>Setting Up Searches on the WN Server</title>

    <link rev="made" href="mailto:john@math.nwu.edu">

    <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
    <meta http-equiv="last-modified" content="Fri, 09 Oct 1998 18:18:09 GMT">
    <meta http-equiv="keywords" content="WN searching">
  </head>

  <body bgcolor="#FFFFFF">
    <p>
      <a href="http://hopf.math.nwu.edu/"><img
        src="images/powered.jpg"
        border="0"
        width="190"
        height="41"
        align="right"
        alt="WN home page"
      ></a>
    </p>

    <strong>Version 2.0.3</strong>

    <br>

    <!-- pnuts --> <a href="security.html">[Previous]</a> <a href="parse.html">[Next]</a> <a href="manual.html">[Up]</a> <a href="manual.html">[Top]</a> <a href="dosearch.html">[Search]</a> <a href="docindex.html">[Index]</a>


    <br clear="right">

    <hr size="4">
    <!-- #start -->

    <h2 align="center">Setting Up Searches on the <em>WN</em> Server</h2>
    <hr size="4">

    <p>
      One of the design goals of <em>WN</em> is provide the maintainer with
      tools to create extensive navigational aids for the server. A variety of
      search mechanisms are available that provide this capability.
    </p>



    <h3>5.1 <a name="title">Title Searches</a></h3>

    <p>
      In response to the <a
      href="http://linux-howto.com/rfc/rfc1500-1999/rfc1738.txt">URL</a>:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=title&gt;
      </code>
    </blockquote>

    <p>
      the server will provide an <a href="http://www.w3c.org/MarkUp/">HTML</a>
      form (automatically generated or prepared by the maintainer) asking for a
      regular expression search term. When supplied the server will search the
      <code>index.cache</code> files in <code>/dir</code> and designated
      subdirectories for a items whose titles contain a match for the search
      term.  An <a href="http://www.w3c.org/MarkUp/">HTML</a> document with a
      menu of these items is returned.  Subdirectories are designated for
      recursive searching by an entry in directory record of the <a
      href="index_desc.html#index"><code>index</code></a> file like:
    </p>

    <blockquote>
      <code>
        <a href="appendixB.html#ddir.subdirs">Subdirs=</a>dir1,dir2,dir3
      </code>
    </blockquote>

    <p>
      You can customize the message offered requesting a search term by
      creating an <a href="http://www.w3c.org/MarkUp/">HTML</a> form whose
      <code>ACTION</code> is the URL
      "<code>http://host/dir/search=title</code>" and which uses the
      <code>GET</code> method to return the search term with
      "<code>NAME=query</code>".
    </p>

    <p>
      The regular expressions recognized by the <em>WN</em> server are the same
      as those of the UNIX <code><a
      href="http://linux-howto.com/man/man1/grep.1.html">grep(1)</a></code>
      utility (though this utility is not used as the server has its own
      regular expression functions).  The more general regular expressions used
      for example in the UNIX <code><a
      href="http://linux-howto.com/man/man1/egrep.1.html">egrep(1)</a></code>
      utility are not supported by <em>WN</em>.
    </p>



    <h3>5.2 <a name="keyword">Keyword Searches</a></h3>

    <p>
      Like <a href="#title">title searches</a> except matches are sought in
      keywords instead of titles.  Keywords for <a
      href="http://www.w3c.org/MarkUp/">HTML</a> documents are automatically
      obtained from <code>&lt;META&gt;</code> headers.  For other documents (or
      <a href="http://www.w3c.org/MarkUp/">HTML</a> documents) they can be
      manually supplied in the <a
      href="index_desc.html#index"><code>index</code></a> file.  This is done
      by including a line like:
    </p>

    <blockquote>
      <code>
        <a href="appendixB.html#fdir.keywords">Keywords=</a>keyword1, keyword2, etc.
      </code>
    </blockquote>

    <p>
      in the relevant document's record in the <a
      href="index_desc.html#index"><code>index</code></a> file.  The URL to use
      to cause this search to be done is:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=keyword&gt;
      </code>
    </blockquote>



    <h3>5.3 <a name="title_keyword">Title/Keyword Searches</a></h3>

    <p>
      Like the above <a href="#keyword">keyword</a> and <a
      href="#title">title</a> searches except the match can be either in the
      keyword or the title.  The URL to use as the <code>ACTION</code> in a
      form or simply to invoke the search is:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=synopsis&gt;
      </code>
    </blockquote>

    <p>
      If a recursive title, keyword or fielded search is requested and some
      directories have <a href="access.html#ip">restricted access</a>, only
      those directories which have the same access file or the same <a
      href="access.html#authenticate">password realm</a> as the directory where
      the search started will be searched.  In fact, if an "<code><a
      href="appendixB.html#ddir.accessfile">Accessfile=</a></code>" directive
      is used the path must be the same for both directories (and must
      necessarily be of the form "<code>Accessfile=~/dir/.access</code>" or
      "<code>Accessfile=/dir/.access</code>" rather than
      "<code>Accessfile=.access</code>").
    </p>



    <h3>5.4 <a name="fielded">Fielded Searches for User Supplied Fields</a></h3>

    <p>
      The maintainer can supply up to 20 additional field values associated
      with a document.  These are used for searching purposes in the same way
      that "<code><a href="appendixB.html#fdir.keywords">Keywords=</a></code>"
      are.  This is intended to give some additional "keyword like" fields, for
      example, document author or document id number.  It works exactly like
      keywords except these values are not extracted from <a
      href="http://www.w3c.org/MarkUp/">HTML</a> files, but must be created
      with a line like:
    </p>

    <blockquote>
      <code>
        <a href="appendixB.html#fdir.field">Field3=</a>any text here
      </code>
    </blockquote>

    <p>
      in the <code><a href="index_desc.html#index">index</a></code> file.  The
      '<code>3</code>' in this example can be replaced with any number from
      <code>0</code> to <code>19</code>.  The URL to use as the
      <code>ACTION</code> in a form or simply to invoke the search in the
      example above is:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=field3&gt;
      </code>
    </blockquote>

    <p>
      Like <a href="#keyword">keyword</a> and <a href="#title">title</a>
      searches the search term for a fielded search can be any UNIX <code><a
      href="http://linux-howto.com/man/man1/grep.1.html">grep(1)</a></code>
      utility like regular expression.
    </p>



    <h3>5.5 <a name="context">Context Searches</a></h3>

    <p>
      Unlike <a href="#keyword">keyword</a>, <a href="#title">title</a> and <a
      href="#fielded">fielded</a> searches this is a full text search of all
      "<code>text/*</code>" documents in one directory (not subdirectories).
      These searches are also limited to the main files -- they will not find
      matches in <a href="parse.html#wrapping">wrappers</a> and <a
      href="parse.html#including">included files</a>.  The returned <a
      href="http://www.w3c.org/MarkUp/">HTML</a> document contains a list of
      titles of documents containing a match each with a sublist of the lines
      from those documents containing the match.  This provides one line of
      context for the match.  For <a href="http://www.w3c.org/MarkUp/">HTML</a>
      documents selecting the matched expression in one of these takes you to
      the document with your viewer focused on the matching location.  The
      primary intent of this feature is to provide full text searching for an
      <a href="http://www.w3c.org/MarkUp/">HTML</a> "document" which might
      consist of a substantial number of files.  It is possible to customize
      the text of the <a href="http://www.w3c.org/MarkUp/">HTML</a> response
      containing the matches.  This is done with a <a
      href="#searchwrapper">Searchwrapper directive</a>.
    </p>

    <p>
      The URL to use as the <code>ACTION</code> in a form or simply to invoke
      the search is:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=context&gt;
      </code>
    </blockquote>

    <p>
      It is possible to mark <a href="http://www.w3c.org/MarkUp/">HTML</a>
      documents with comments so that only part of them is searched.  This is
      done with lines consisting of the comment
      "<code>&lt;!--&nbsp;#search_off&nbsp;--&gt;</code>" which turns off
      searching until the line consisting of
      "<code>&lt;!--&nbsp;#search_on&nbsp;--&gt;</code>" is encountered.
    </p>



    <h3>5.6 <a name="grep">Grep Searches</a></h3>

    <p>
      A grep search is just like a <a href="#context">context search</a>,
      except that only a list of anchors pointing to files containing a match
      is returned.  There are no lines of context showing the match. To do a
      grep search on the files in directory <code>dir</code> use:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=grep&gt;
      </code>
    </blockquote>



    <h3>5.7 <a name="line">Line Searches</a></h3>

    <p>
      A line search is just like a <a href="#context">context search</a>,
      except that only one list of all matching lines is returned, instead of
      the matching lines being sublists of a list of files containing a match.
      That is, all the items in sublists of a context search are concatenated
      in one large list of lines containing matches.  The matching items are
      still anchors pointing to items in their respective files.  To do a line
      search on the files in directory <code>dir</code> use:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/search=line&gt;
      </code>
    </blockquote>



    <h3>5.8 <a name="fgrep">File Context and Grep Searches</a></h3>

    <p>
      A file context search is just like a <a href="#context">context
      search</a>, except limited to a single file.  The file grep search
      returns a <code>text/html</code> document containing the lines in the
      file matching matching the regular expression.  These lines will be
      converted to plain text and surrounded by <code>&lt;pre&gt;</code> and
      <code>&lt;/pre&gt;</code> tags.  This is done because isolated tags or
      partial tags taken from an <a href="http://www.w3c.org/MarkUp/">HTML</a>
      document would be unlikely to function properly.  It is likely that you
      will want to use a <a href="#searchwrapper">Searchwrapper directive</a>
      with a file grep search.
    </p>

    <p>
      The URL's to invoke these searches on file <code>foo</code> are:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/foo;search=context&gt;
        <br>
        &lt;http://host/dir/foo;search=grep&gt;
      </code>
    </blockquote>



    <h3>5.9 <a name="types">Search a Directory or Search a Hierarchy?</a></h3>

    <p>
      The different searches described above are of two types: those that
      search the <code>index.cache</code> files like <a
      href="#fielded">field</a>, <a href="#keyword">keyword</a> and <a
      href="#title">title</a> searches and those that do full text searches of
      multiple files, like <a href="#context">context</a>, <a
      href="#grep">grep</a>, <a href="#fgrep">field grep</a> and <a
      href="#line">line</a> searches.  The first type recursively descends all
      subdirectories listed in a "<code><a
      href="appendixB.html#ddir.subdirs">Subdirs=</a></code>" directive and
      searches all the <code>index.cache</code> files.  The second only
      searches files in the one directory specified in the search.
    </p>

    <p>
      The reason for this is efficiency.  <a href="#context">context</a>, <a
      href="#grep">grep</a>, <a href="#fgrep">field grep</a> and <a
      href="#line">line</a> searches are not a replacement for <a
      href="http://www.wais.com">WAIS</a>, <a
      href="http://glimpse.cs.arizona.edu">glimpse</a>, <a
      href="http://glimpse.cs.arizona.edu/webglimpse/">webglimpse</a> or some
      other indexed search engine.  The intent of these searches is to allow a
      full text search of a single conceptual <a
      href="http://www.w3c.org/MarkUp/">HTML</a> document that is made up of a
      number of files with links.  These searches work great with something
      like the HTML4.0 specification (see <a
      href="http://hopf.math.nwu.edu/html4/">http://hopf.math.nwu.edu/html4/</a>)
      which consists of a number of files of moderate size, but they would be
      very slow with 1000 files spread out in a data hierarchy.  For that you
      really need an indexing search engine.
    </p>

    <p>
      Another limitation of these searches is that they will not find matches
      in <a href="parse.html#wrapping">wrappers</a> and <a
      href="parse.html#including">included files</a>.
    </p>

    <p>
      On the other hand, all of the searching methods listed above are built
      into the server and require no additional effort for the maintainer.  You
      don't need to produce or maintain an index. They are simply referenced
      with URLs like "<code>&lt;http://host/dir/search=context&gt;</code>"
      where <code>/dir</code> is any directory containing files to be served
      and an <code>index.cache</code> listing them.  Of course search
      permission can be denied for any directory or any file contained in that
      directory.
    </p>



    <h3>5.10 <a name="list">List Searches</a></h3>

    <p>
      The server will search an <a href="http://www.w3c.org/MarkUp/">HTML</a>
      document looking for an unordered list of anchors linking to WWW objects.
      The contents of each anchor will be searched for a match to the supplied
      regular expression.  The search returns an <a
      href="http://www.w3c.org/MarkUp/">HTML</a> document containing an
      unordered list of those anchors with a match.  This is quite useful when
      combined with the <code><a
      href="utility.html#wn_mkdigest">wn_mkdigest</a></code> utility which
      creates <a href="http://www.w3c.org/MarkUp/">HTML</a> documents to be
      searched in this way from files with internal structure like mail or news
      digests, mailing lists, etc.
    </p>

    <p>
      The URL to invoke this search on file <code>foo</code>:
    </p>

    <blockquote>
      <code>
        &lt;http://host/dir/foo;search=list&gt;
      </code>
    </blockquote>



    <h3>5.11 <a name="index">Index Searches</a></h3>

    <p>
      Indexed searches can be supported in <em>WN</em> by auxiliary modules.
      Two such modules, <a href="module.html#isearch">wnseven_m and
      wnsectsearch</a>, are provided as examples and maintainers may wish to
      create others.  To use such a module you should have a form action be
      something like <code>http://host/dir/search=index</code>.
    </p>

    <p>
      Then in the <code><a href="index_desc.html#index">index</a></code> file
      in the directory <code>dir</code> you should have a line like:
    </p>

    <blockquote>
      <code>
        <a
        href="appendixB.html#ddir.search-module">Search-Module=</a>/full/path/to/searchmod
      </code>
    </blockquote>

    <p>
      The program <code>searchmod</code> should read the environment variable
      <code>QUERY_STRING</code> and return a partial <a
      href="http://www.w3c.org/MarkUp/">HTML</a> document.  The typical case
      would be the program returns an unordered list of anchors to documents
      containing a match to the query string.  This list can be wrapped by
      including a "<code><a
      href="appendixB.html#searchwrapper">Searchwrapper=</a></code>" directory
      record.  If it is not, then a default wrapper with text like "<code>Here
      are the matches for your search</code>" is supplied.
    </p>



    <h3>5.12 <a name="mode">Search Modes</a></h3>

    <p>
      The different types of searches, (e.g. <a href="#keyword">keyword</a>, <a
      href="#context">context</a>, etc), are called the <em>modes</em> used by
      the search.  Normally the mode is set by adding, for example
      "<code>search=context</code>" to the end of a URL.  However, if an <a
      href="http://www.w3c.org/MarkUp/">HTML</a> form is used to initiate the
      search, it may be desirable to allow the mode to be selected by a form
      variable.  Thus an <a href="http://www.w3c.org/MarkUp/">HTML</a> form
      like:
    </p>

    <blockquote>
      <pre>
&lt;form action="search=mode" method="GET"&gt;
Enter your search term &lt;input name="query" size=15&gt;
&lt;input type="submit" value="Search"&gt; by
&lt;input type="radio" name="mode" value="title" checked&gt; title or
&lt;input type="radio" name="mode" value="keyword"&gt; keywords
&lt;/form&gt;
      </pre>
    </blockquote>

    <p>
      will execute either a title or a keyword search depending on whether the
      user checks the radio button for "<code>title</code>" or
      "<code>keyword</code>".  The URL requested will end with
      "<code>search=mode</code>", but actually it could be anything since the
      "<code>mode=title</code>" (if that is what is checked) which will be in
      the query part of the URL will override whatever follows
      "<code>search=</code>" in the base URL.
    </p>



    <h3>5.13 <a name="searchwrapper">Searchwrappers</a></h3>

    <p>
      By default when a search is done an <a
      href="http://www.w3c.org/MarkUp/">HTML</a> file is created with text like
      "<code>Here are the matches for ...</code>".  You may wish to customize
      this response which is done with the "<code><a
      href="appendixB.html#fdir.searchwrapper">Searchwrapper=</a></code>"
      directive in either a file record or directory record of the <code><a
      href="index_desc.html#index">index</a></code> file.
    </p>

    <p>
      The line:
    </p>

    <blockquote>
      <code>
        <a
        href="appendixB.html#fdir.searchwrapper">Searchwrapper=</a>swrap.html
      </code>
    </blockquote>

    <p>
      specifies that the <a href="http://www.w3c.org/MarkUp/">HTML</a> file
      <code>swrap.html</code> in the current directory should be used as a
      wrapper for the output of all searches on this directory (if it is a
      directory record entry) or file (if it is a file directive).  This
      wrapper differs from other wrappers in that it can have only a single
      "<code>&lt;!--&nbsp;#include&nbsp;--&gt;</code>" line.  An unordered list
      of anchors to the matching items will be inserted at the location of this
      line.  You can, of course, insert the client supplied search term by use
      of the line "<code>&lt;!--&nbsp;#query&nbsp;--&gt;</code>" in this file.
    </p>

    <p>
      The remainder of this file can be anything you wish and is often an <a
      href="http://www.w3c.org/MarkUp/">HTML</a> form allowing subsequent
      searches.
    </p>

    <p>
      If a search fails to find any matches then a default <a
      href="http://www.w3c.org/MarkUp/">HTML</a> response indicating this is
      sent.  This response can also be customized but only if a "<code><a
      href="appendixB.html#fdir.searchwrapper">Searchwrapper=</a></code>" is
      also used.  The line:
    </p>

    <blockquote>
      <code>
        <a href="appendixB.html#ddir.nomatchsub">Nomatchsub=</a>foo.html
      </code>
    </blockquote>

    <p>
      specifies that the <a href="http://www.w3c.org/MarkUp/">HTML</a> file
      <code>foo.html</code> in the current directory should be used for the
      output of all searches (<a href="#title">title</a>, <a
      href="#keyword">keyword</a>, etc) on this directory (or file if it is a
      file directive) which return no matches.  If "<code><a
      href="appendixB.html#ddir.nomatchsub">Nomatchsub=</a></code>" is used and
      a "<code><a
      href="appendixB.html#fdir.searchwrapper">Searchwrapper=</a></code>" has
      not been defined an error is logged and the <code>nomatchsub</code> file
      is ignored.  The <code>nomatchsub</code> file must be in the directory
      being searched and its name must not contain a '<code>/</code>'.
    </p>



    <!-- #end -->
    <hr size="4">

    <address>
      <em>WN</em> version 2.0.3
      <br>
      Copyright &copy; 1998 <a href="mailto:john@math.nwu.edu">John Franks
      &lt;john@math.nwu.edu&gt;</a>
      <br>
      licensed under the <a href="http://www.opencontent.org/opl.html">
      OpenContent Public License</a>
      <br>
      last-modified: Fri, 09 Oct 1998 18:18:09 GMT
    </address>

    <!-- pnuts --> <a href="security.html">[Previous]</a> <a href="parse.html">[Next]</a> <a href="manual.html">[Up]</a> <a href="manual.html">[Top]</a> <a href="dosearch.html">[Search]</a> <a href="docindex.html">[Index]</a>
  </body>
</html>