1HXINDEX(1) HTML-XML-utils HXINDEX(1)
2
6 hxindex - insert an index into an HTML document
7
9 hxindex [ -t ] [ -x ] [ -n ] [ -f ] [ -c classes ] [ -b base ] [ -i
10 indexdb ] [--] [ file-or-URL ]
11
13 The hxindex looks for terms to be indexed in a document, collects them,
14 turns them into target anchors and creates a sorted index as an HTML
15 list, which is inserted at the place of a placeholder in the document.
16 The resulting document is written to standard output.
17 The index is inserted at the place of a comment of the form
19 <!--index-->
21 or between two comments of the form
23 <!--begin-index-->
25 ...
26 <!--end-index-->
27 In the latter case, all existing content between the two comments is
29 removed first.
30 Index terms are either elements of type <dfn> or elements with a class
32 attribute of "index". (For backward compatibility, also class
33 attributes "index-inst" and "index-def" are recognized.) <dfn> elements
34 (and class "index-def") are considered more important than elements
35 with class "index" and will appear in bold in the generated index.
36 The option -c adds additional classes, that are aliases for "index".
38 By default, the contents of the element are taken as the index term.
40 Here are two examples of occurrences of the index term "shoe":
41 A <dfn>shoe</dfn> is a piece of clothing that...
43 completed by a leather <span class="index">shoe</span>...
44 If the term to be indexed is not equal to the contents of the element,
47 the title attribute can be used to give the correct term:
48 ... <dfn title="shoe">Shoes</dfn> are pieces of clothing that...
50 ... with two leather <span class="index" title="shoe">shoes</span>...
51 The title attribute must also be used when the index term is a subterm
54 of another. Subterms appear indented in the index, under their head
55 term. To define a subterm, use a title attribute with two exclamation
56 marks ("!!") between the term and the subterm, like this:
57 <dfn title="shoe!!leather">...</dfn>
59 <dfn title="shoe!!invention of">...</dfn>
60 <em class="index" title="shoe!!protective!!steel nosed">...</em>
61 As the last example above shows, there can be multiple levels of sub-
63 subterms.
64 The title attribute also allows multiple index terms to be associated
66 with a single occurrence. The multiple terms are separated with a ver‐
67 tical bar ("|"). Compare the following examples with the ones above:
68 <dfn title="shoe|boot">...</dfn>
70 <dfn title="shoe!!invention of|inventions!!shoe">...</dfn>
71 These two elements both insert two terms into the index. Note that the
73 second example above combines subterms and multiple terms.
74 It is possible to run index on a file that already has an index. The
76 old target anchors and the old index will be removed before being re-
77 generated.
78
80 The following options are supported:
81 -t By default, hxindex adds an ID attribute to the element that
83 contains the occurrence of a term and also inserts an <a>
84 element inside it with a name attribute equal to the ID. This
85 is to allow old browsers that ignore ID attributes, such as
86 Netscape 4, to find the target as well. The -t option sup‐
87 presses the <a> element.
88 -x This option turns on XML syntax conventions: empty elements
90 will end in /> instead of > as in HTML. -x implies -t.
91 -i indexdb
93 hxindex can read an initial index from a file and write the
94 merged collection of index terms back to that file. This
95 allows an index to span several documents. The -i option is
96 used to give the name of the file that contains the index.
97 -b base This option is useful in combination with -i to give the base
99 URL reference of the document. By default, hxindex will store
100 links to occurrences in the indexdb file in the form #anchor,
101 but when -b is given, the links will look like base#anchor
102 instead.
103 -c class[,class[,...]]
105 Normal index terms are recognized because they have a class
106 of "index". The -c option adds additional, comma-separated
107 class names that will be considered aliases for "index".
108 E.g., -c instance will make sure that <span
109 class="instance">term</span> is recognized as a term for the
110 index.
111 -n By default, the index consists of links with "#" as the
113 anchor text. Option -n causes the link text to consist of
114 the section numbers of the sections in which the terms occur,
115 falling back to "#" only if no section number could be found.
116 Section numbers are found by looking for the nearest preced‐
117 ing start tag with a class of "secno" or "no-num". In the
118 case of "secno", the contents of that element are taken as
119 the section number. In the case of "no-num" the section is
120 assumed to have no number and hxindex will print a "#"
121 instead. These classes are also used by hxnum(1), so it is
122 useful to run hxindex after hxnum, e.g.,
123 hxnum myfile.html | hxindex -n >mynewfile.html
125 -f Remove title attributes that were used for the index as well
128 as the comments that delimit the inserted index. This avoids
129 that browsers display these attributes. Note that hxindex
130 cannot be run again on its own output if this option is used.
131 (Mnemonic: "freeze" or "final".)
132
134 The following operand is supported:
135 file-or-URL
137 The name of an HTML or XML file or the URL of one. If absent,
138 or if the file is "-", standard input is read instead.
139
141 The input is assumed to be in UTF-8, but the current locale is used to
142 determine the sorting order of the index terms. I.e., hxindex looks at
143 the LANG, LC_ALL and/or LC_COLLATE environment variables. See
144 locale(1).
145
147 The following exit values are returned:
148 0 Successful completion.
150 >0 An error occurred in parsing the HTML file.
152
154 asc2xml(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1),
155 xml2asc(1), locale(1), UTF-8 (RFC 2279)
156
158 Assumes UTF-8 as input. Doesn't expand character entities (apart from
159 the standard ones: "&", "<", ">" and """). Instead, pipe
160 the input through hxunent(1) and, if needed, asc2xml(1) to convert it
161 to UTF-8.
1625.x 21 Nov 2008 HXINDEX(1)