You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
514 lines
14 KiB
514 lines
14 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>
|
|
ht://Dig: htsearch
|
|
</title>
|
|
</head>
|
|
<body bgcolor="#eef7ff">
|
|
<h1>
|
|
htsearch
|
|
</h1>
|
|
<p>
|
|
ht://Dig Copyright © 1995-2004 <a href="THANKS.html">The ht://Dig Group</a><br>
|
|
Please see the file <a href="COPYING">COPYING</a> for
|
|
license information.
|
|
</p>
|
|
<hr size="4" noshade>
|
|
<h2>
|
|
Output Templates
|
|
</h2>
|
|
<p>
|
|
The htsearch program will normally produce HTML output. In this
|
|
process it makes extensive use of template in which variables
|
|
will be substituted. The templates are specified in the
|
|
configuration file. The configuration file attributes defining
|
|
these templates are:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<a href="attrs.html#search_results_header">
|
|
search_results_header</a>
|
|
</li>
|
|
<li>
|
|
<a href="attrs.html#search_results_footer">
|
|
search_results_footer</a>
|
|
</li>
|
|
<li>
|
|
<a href="attrs.html#search_results_wrapper">
|
|
search_results_wrapper</a>
|
|
</li>
|
|
<li>
|
|
<a href="attrs.html#nothing_found_file">
|
|
nothing_found_file</a>
|
|
</li>
|
|
<li>
|
|
<a href="attrs.html#syntax_error_file">
|
|
syntax_error_file</a>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
In addition to these files, the search results are also
|
|
produced with the use of templates. The result templates are
|
|
a bit more complicated because they can be specified at
|
|
runtime using an HTML menu. They are specified using the <a
|
|
href="attrs.html#template_map">template_map</a> configuration
|
|
file attribute. This attribute contains a list of strings
|
|
triplets. For each triplet of strings, the elements have the
|
|
following meaning:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
the name that will appear in the FORMAT menu (see below)
|
|
</li>
|
|
<li>
|
|
the internal name used by htsearch for this result template
|
|
</li>
|
|
<li>
|
|
the base filename for the template.
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
There are two predefined templates that are used by default.
|
|
They have the internal names <em>builtin-long</em> and <em>
|
|
builtin-short</em>. As such, the default value for the <em>
|
|
template_map</em> attribute is as follows:
|
|
</p>
|
|
<blockquote>
|
|
Long builtin-long builtin-long \<br>
|
|
Short builtin-short builtin-short
|
|
</blockquote>
|
|
<p>
|
|
Which means that there will be two ways to display the search
|
|
results: a "Long" and a "Short" way. The first template listed
|
|
will always be the default one for the first search.
|
|
Thereafter, the default will be whatever was selected for the
|
|
previous search.
|
|
</p>
|
|
<h4>
|
|
Result template files
|
|
</h4>
|
|
<p>
|
|
When a custom template is required, one or more template files
|
|
need to be created and referenced in the <em>template_map</em>
|
|
attribute. These templates are user-selectable from the search
|
|
form. It is also possible to select result templates based on
|
|
URL patterns of the search matches, using the
|
|
<em>template_patterns</em> attribute. This allows distinct visual
|
|
styles to be used for matches on different web sites.
|
|
</p>
|
|
<p>
|
|
There are many variables that can be substituted into these
|
|
templates. Not all of them make sense for each file, so not
|
|
all of them will be substituted for every file, as noted below.
|
|
<!-- Should explain "matchTemplate" more explicitly... How? -->
|
|
In addition, all
|
|
of the standard CGI environment variables are available, and
|
|
listed in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">cgi
|
|
specification</a>. Variables will be substituted normally
|
|
with the format $(VAR), escaped for use in a URL with the
|
|
format $%(VAR), URL-encoding decoded with the format $=(VAR),
|
|
and HTML-escaped with the format $&(VAR). The variables are:
|
|
</p>
|
|
<dl>
|
|
<dt>
|
|
<strong>ANCHOR</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
Expands to the named anchor found just before the first match; it
|
|
includes "#" at the start so it can be directly appended to the URL
|
|
variable. If no anchor was found, ANCHOR is empty.
|
|
</dd>
|
|
<dt>
|
|
<strong>BACKLINKS</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The number of links <strong>to</strong> the current match.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="CGI">CGI</a></strong>
|
|
</dt>
|
|
<dd>
|
|
Unless the configuration file sets a different value,
|
|
this expands to whatever the SCRIPT_NAME environment
|
|
variable is. See the
|
|
<a href="attrs.html#script_name">script_name</a>
|
|
configuration file attribute for more information.
|
|
</dd>
|
|
<dt>
|
|
<strong>CONFIG</strong>
|
|
</dt>
|
|
<dd>
|
|
The <a href="hts_form.html#config">configuration file</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>CURRENT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The number of the current match.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="DESCRIPTION">DESCRIPTION</a></strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The first URL description for the matched document. See below.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="DESCRIPTIONS">DESCRIPTIONS</a></strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
A list of <a href="attrs.html#description_factor">URL text
|
|
descriptions</a> for the matched document. The
|
|
entries in the list are separated by <br>. These are the
|
|
text used between the <a href...> and </a>tags.
|
|
These are controlled by the
|
|
<a href="attrs.html#max_descriptions">max_descriptions</a> and
|
|
<a href="attrs.html#max_description_length">max_description_length</a>
|
|
configuration attributes.
|
|
</dd>
|
|
<dt>
|
|
<strong>DOCID</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The internal ID for the document for the current match.
|
|
</dd>
|
|
<dt>
|
|
<strong>EXCERPT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The relevant <a href="attrs.html#excerpt_show_top">excerpt</a>
|
|
for the current match.
|
|
</dd>
|
|
<dt>
|
|
<strong>EXCLUDE</strong>
|
|
</dt>
|
|
<dd>
|
|
A <a href="hts_form.html#exclude">list of words excluded</a>
|
|
from the search, separated by '|'.
|
|
</dd>
|
|
<dt>
|
|
<strong>FIRSTDISPLAYED</strong>
|
|
</dt>
|
|
<dd>
|
|
The index of the first match on this page.
|
|
</dd>
|
|
<dt>
|
|
<strong>FORMAT</strong>
|
|
</dt>
|
|
<dd>
|
|
Expands to an HTML menu of all the available formats. The
|
|
current format will be the default one.
|
|
The menu is composed of choices itemized in the
|
|
<a href="attrs.html#template_map">template_map</a>
|
|
attribute. The expansion of this template variable is
|
|
described in more detail in the
|
|
<a href="hts_selectors.html">select list documentation</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>HOPCOUNT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The distance of this match away from the starting
|
|
document(s).
|
|
</dd>
|
|
<dt>
|
|
<strong>KEYWORDS</strong>
|
|
</dt>
|
|
<dd>
|
|
A string of the search keywords with spaces in between, as
|
|
specified in the
|
|
<a href="hts_form.html#keywords"><em>keywords</em> input
|
|
parameter</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>LASTDISPLAYED</strong>
|
|
</dt>
|
|
<dd>
|
|
The index of the last match on this page.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="LOGICAL_WORDS">LOGICAL_WORDS</a></strong>
|
|
</dt>
|
|
<dd>
|
|
A string of the <a href="hts_form.html#words">search words</a>
|
|
with "and", "or" or "not" between the words, depending on the
|
|
<a href="hts_form.html#match_method">type of search</a>.
|
|
(These values are overridden by the
|
|
<a href="attrs.html#boolean_keywords">boolean_keywords</a>
|
|
attribute.)
|
|
</dd>
|
|
<dt>
|
|
<strong>MATCH_MESSAGE</strong>
|
|
</dt>
|
|
<dd>
|
|
This is either <code>all</code> or <code>any</code> depending on
|
|
the <a href="hts_form.html#match_method">match method</a> used.
|
|
(These values are overridden by the
|
|
<a href="attrs.html#method_names">method_names</a>
|
|
attribute.)
|
|
</dd>
|
|
<dt>
|
|
<strong>MATCHES</strong>
|
|
</dt>
|
|
<dd>
|
|
The total number of matches that were found.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="MATCHES_PER_PAGE">MATCHES_PER_PAGE</a></strong>
|
|
</dt>
|
|
<dd>
|
|
The configured <a href="hts_form.html#matchesperpage">maximum
|
|
number of matches</a> on this page.
|
|
</dd>
|
|
<dt>
|
|
<strong>MAX_STARS</strong>
|
|
</dt>
|
|
<dd>
|
|
The configured <a href="attrs.html#max_stars">maximum number
|
|
of stars</a> to display in matches.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="METADESCRIPTION">METADESCRIPTION</a></strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The meta description text (if any) for the matched document.
|
|
</dd>
|
|
<dt>
|
|
<strong>METHOD</strong>
|
|
</dt>
|
|
<dd>
|
|
Expands to an HTML menu of all the available matching
|
|
methods. The current method will be the default one.
|
|
The menu is composed of choices itemized in the
|
|
<a href="attrs.html#method_names">method_names</a>
|
|
attribute. The expansion of this template variable is
|
|
described in more detail in the
|
|
<a href="hts_selectors.html">select list documentation</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>MODIFIED</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The date and time the document was last modified
|
|
</dd>
|
|
<dt>
|
|
<strong>NEXTPAGE</strong>
|
|
</dt>
|
|
<dd>
|
|
This expands to the value of the
|
|
<a href="attrs.html#next_page_text">next_page_text</a> or
|
|
<a href="attrs.html#no_next_page_text">no_next_page_text</a>
|
|
attributes depending on whether there is a next page or not.
|
|
If there is only one page of output, this is empty, regardless
|
|
of the setting of no_next_page_text.
|
|
</dd>
|
|
<dt>
|
|
<strong>NSTARS</strong>
|
|
</dt>
|
|
<dd>
|
|
The number of stars calculated for this document as an
|
|
integer, up to a maximum specified by the <a
|
|
href="attrs.html#max_stars">max_stars</a> attribute.
|
|
</dd>
|
|
<dt>
|
|
<strong>PAGE</strong>
|
|
</dt>
|
|
<dd>
|
|
The current page number. Equal to the
|
|
<a href="hts_form.html#page">page</a> CGI argument, or 1 by
|
|
default.
|
|
</dd>
|
|
<dt>
|
|
<strong>PAGEHEADER</strong>
|
|
</dt>
|
|
<dd>
|
|
This expands to either the value of the
|
|
<a href="attrs.html#page_list_header">page_list_header</a> or
|
|
<a href="attrs.html#no_page_list_header">no_page_list_header</a>
|
|
attributes depending on how many pages there are.
|
|
</dd>
|
|
<dt>
|
|
<strong>PAGELIST</strong>
|
|
</dt>
|
|
<dd>
|
|
This expands to a list of hyperlinks using the
|
|
<a href="attrs.html#page_number_text">page_number_text</a> and
|
|
<a href="attrs.html#no_page_number_text">no_page_number_text</a>
|
|
attributes. For the current page, it displays
|
|
no_page_number_text without a hyperlink. Other pages have a
|
|
hyperlink, and use page_number_text.
|
|
</dd>
|
|
<dt>
|
|
<strong>PAGES</strong>
|
|
</dt>
|
|
<dd>
|
|
The total number of pages.
|
|
</dd>
|
|
<dt>
|
|
<strong>PERCENT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The match score as a percentage. Its range is 1 to 100,
|
|
without a percent sign. The minimum is always 1 so the
|
|
variable can be used as the value for an HTML WIDTH
|
|
attribute.
|
|
</dd>
|
|
<dt>
|
|
<strong>PLURAL_MATCHES</strong>
|
|
</dt>
|
|
<dd>
|
|
If the <strong>MATCHES</strong> variable is other than 1, this
|
|
will be a single 's'.
|
|
(This value is overridden by the
|
|
<a href="attrs.html#plural_suffix">plural_suffix</a>
|
|
attribute.)
|
|
</dd>
|
|
<dt>
|
|
<strong>PREVPAGE</strong>
|
|
</dt>
|
|
<dd>
|
|
This expands to the value of the
|
|
<a href="attrs.html#prev_page_text">prev_page_text</a> or
|
|
<a href="attrs.html#no_prev_page_text">no_prev_page_text</a>
|
|
attributes depending on whether there is a previous page or not.
|
|
If there is only one page of output, this is empty, regardless
|
|
of the setting of no_prev_page_text.
|
|
</dd>
|
|
<dt>
|
|
<strong>RESTRICT</strong>
|
|
</dt>
|
|
<dd>
|
|
The <a href="hts_form.html#restrict">list of patterns</a> which
|
|
must be matched by the returned URLs, separated by '|'.
|
|
</dd>
|
|
<dt>
|
|
<strong>SCORE</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The score of the current match
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="SELECTED_FORMAT">SELECTED_FORMAT</a></strong>
|
|
</dt>
|
|
<dd>
|
|
The currently selected <a href="hts_form.html#format">format</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="SELECTED_METHOD">SELECTED_METHOD</a></strong>
|
|
</dt>
|
|
<dd>
|
|
The currently selected <a href="hts_form.html#method">matching
|
|
method</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong><a name="SELECTED_SORT">SELECTED_SORT</a></strong>
|
|
</dt>
|
|
<dd>
|
|
The currently selected <a href="hts_form.html#sort">sorting
|
|
method</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>SIZE</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The size of the document for the current match
|
|
</dd>
|
|
<dt>
|
|
<strong>SIZEK</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The size in kilobytes of the document for the current match
|
|
</dd>
|
|
<dt>
|
|
<strong>SORT</strong>
|
|
</dt>
|
|
<dd>
|
|
Expands to an HTML menu of all the available sorting
|
|
methods. The current method will be the default one.
|
|
The menu is composed of choices itemized in the
|
|
<a href="attrs.html#sort_names">sort_names</a>
|
|
attribute. The expansion of this template variable is
|
|
described in more detail in the
|
|
<a href="hts_selectors.html">select list documentation</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>STARSLEFT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
A set of HTML <img> tags with the
|
|
<a href="attrs.html#star_image">stars</a> aligned on the left.
|
|
</dd>
|
|
<dt>
|
|
<strong>STARSRIGHT</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
A set of HTML <img> tags with the stars
|
|
<a href="attrs.html#star_image">stars</a> aligned on the right.
|
|
</dd>
|
|
<dt>
|
|
<strong>STARTYEAR</strong>, <strong>STARTMONTH</strong>, <strong>STARTDAY</strong>,
|
|
<strong>ENDYEAR</strong>, <strong>ENDMONTH</strong>, <strong>ENDDAY</strong>
|
|
</dt>
|
|
<dd>
|
|
The currently specified <a href="hts_form.html#startyear">date
|
|
range</a> for restricting search results.
|
|
</dd>
|
|
<dt>
|
|
<strong>SYNTAXERROR</strong>
|
|
(Only in
|
|
<a href="attrs.html#syntax_error_file">syntax_error_file</a>)
|
|
</dt>
|
|
<dd>
|
|
Is the text of the boolean expression syntax error.
|
|
</dd>
|
|
<dt>
|
|
<strong>TITLE</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The title of the document for the current match
|
|
</dd>
|
|
<dt>
|
|
<strong>URL</strong>
|
|
(Only in matchTemplate)
|
|
</dt>
|
|
<dd>
|
|
The URL to the document for the current match
|
|
</dd>
|
|
<dt>
|
|
<strong>VERSION</strong>
|
|
</dt>
|
|
<dd>
|
|
The ht://Dig <a href="attrs.html#version">version number</a>.
|
|
</dd>
|
|
<dt>
|
|
<strong>WORDS</strong>
|
|
</dt>
|
|
<dd>
|
|
A string of the <a href="hts_form.html#words">search words</a>
|
|
with spaces in between.
|
|
</dd>
|
|
</dl>
|
|
<hr size="4" noshade>
|
|
|
|
Last modified: $Date: 2004/05/28 13:15:18 $
|
|
|
|
</body>
|
|
</html>
|