1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
|
<!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>
|
