1man(1) General Commands Manual man(1)
2
6 index - insert an index into an HTML document
7
9 index [ -t ] [ -x ] [ -c classes ] [ -b base ] [ -i indexdb ] [--] [
10 file-or-URL ]
11
13 The index 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 <!--end-index-->
26 In the latter case, all existing content between the two comments is
28 removed first.
29 Index terms are either elements of type <dfn> or elements with a class
31 attribute of "index". (For backward compatibility, also class
32 attributes "index-inst" and "index-def" are recognized.) <dfn> elements
33 (and class "index-def") are considered more important than elements
34 with class "index" and will appear in bold in the generated index.
35 The option -c adds additional classes, that are aliases for fI"index".
37 By default, the contents of the element are taken as the index term.
39 Here are two examples of occurences of the index term "shoe":
40 A <dfn>shoe</dfn> is a piece of clothing that...
42 completed by a leather <span class="index">shoe</span>...
43 If the term to be indexed is not equal to the contents of the element,
46 the title attribute can be used to give the correct term:
47 The title attribute must also be used when the index term is a subterm
51 of another. Subterms appear indented in the index, under their head
52 term. To define a subterm, use a title attribute with two exclamation
53 marks ("!!") between the term and the subterm, like this:
54 <dfn title="shoe!!leather">...</dfn>
56 <dfn title="shoe!!invention of">...</dfn>
57 <em class="index" title="shoe!!protective!!steel nosed">...</em>
58 As the last example above shows, there can be multiple levels of sub-
60 subterms.
61 The title attribute also allows multiple index terms to be assiciated
63 with a single occurrence. The multiple terms are separated with a ver‐
64 tical bar ("|"). Compare the following examples with the ones above:
65 <dfn title="shoe|boot">...</dfn>
67 <dfn title="shoe!!invention of|inventions!!shoe">...</dfn>
68 These two elements both insert two terms into the index. Note that the
70 second example above combines subterms and multiple terms.
71 It is possible to run index on a file that already has an index. The
73 old target anchors and the old index will be removed before being re-
74 generated.
75
77 The following options are supported:
78 -t By default, index adds an ID attribute to the element that
80 contains the occurrence of a term and also inserts an <a>
81 element inside it with a name attribute equal to the ID. This
82 is to allow old browsers that ignore ID attributes, such as
83 Netscape 4, to find the target as well. The -t option sup‐
84 presses the <a> element.
85 -x This option turns on XML syntax conventions: empty elements
87 will end in /> instead of > as in HTML. -x implies -t.
88 -i indexdb
90 index can read an initial index from a file and write the
91 merged collection of index terms back to that file. This
92 allows an index to span several documents. The -i option is
93 used to give the name of the file that contains the index.
94 -b base This option is useful in combination with -i to give the base
96 URL reference of the document. By default, index will store
97 links to occurrences in the indexdb file in the form file‐
98 name#anchor, but when -b is given, the links will look like
99 base#anchor instead.
100 -c class[,class[,...]]
102 Normal index terms are recognized because they have a class
103 of "index". The -c option adds additional, comma-separated
104 class names that will be considered aliases for "index".
105 E.g., -c instance will make sure that <span
106 class="instance">term</span> is recognized as a term for the
107 index.
108
110 The following operand is supported:
111 file-or-URL
113 The name of an HTML or XML file or the URL of one. If absent,
114 or if the file is "-", standard input is read instead.
115
117 The following exit values are returned:
118 0 Successful completion.
120 >0 An error occurred in the parsing the HTML file.
122
124 xml2asc(1), UTF-8 (RFC 2279), normalize(1), num(1), toc(1), html‐
125 prune(1). unent(1) asc2xml(1)
126
128 Assumes UTF-8 as input. Doesn't expand character entities. Instead pipe
129 the input through unent(1) and asc2xml(1) to convert it to UTF-8.
130 11 Sep 2001 man(1)