Ubuntu Manpage: hxindex - insert an index into an HTML document

NAME

       hxindex - insert an index into an HTML document

SYNOPSIS

       hxindex [ -t ] [ -x ] [ -n ] [ -f ] [ -r ] [ -c classes ] [ -b base ] [ -i indexdb ] [ -s template ] [ -u
       phrase ] [--] [ file-or-URL ]

DESCRIPTION

       The  hxindex  looks  for terms to be indexed in a document, collects them, turns them into target anchors
       and creates a sorted index as an HTML list, which is inserted at  the  place  of  a  placeholder  in  the
       document. The resulting document is written to standard output.

       The index is inserted at the place of a comment of the form

           <!--index-->

       or between two comments of the form

           <!--begin-index-->
           ...
           <!--end-index-->

       In the latter case, all existing content between the two comments is removed first.

       Index  terms  are  either  elements  of  type  <dfn>  or elements with a class attribute of "index". (For
       backward compatibility, also  class  attributes  "index-inst"  and  "index-def"  are  recognized.)  <dfn>
       elements  (and class "index-def") are considered more important than elements with class "index" and will
       appear in bold in the generated index.

       The option -c adds additional classes, that are aliases for "index".

       By default, the contents of the element  are  taken  as  the  index  term.   Here  are  two  examples  of
       occurrences of the index term "shoe":

           A <dfn>shoe</dfn> is a piece of clothing that...
           completed by a leather <span class="index">shoe</span>...

       If the term to be indexed is not equal to the contents of the element, the title attribute can be used to
       give the correct term:

           ... <dfn title="shoe">Shoes</dfn> are pieces of clothing that...
           ... with two leather <span class="index" title="shoe">shoes</span>...

       The  title  attribute  must  also  be  used  when the index term is a subterm of another. Subterms appear
       indented in the index, under their head term. To define  a  subterm,  use  a  title  attribute  with  two
       exclamation marks ("!!") between the term and the subterm, like this:

           <dfn title="shoe!!leather">...</dfn>
           <dfn title="shoe!!invention of">...</dfn>
           <em class="index" title="shoe!!protective!!steel nosed">...</em>

       As the last example above shows, there can be multiple levels of sub-subterms.

       The  title  attribute  also  allows  multiple  index terms to be associated with a single occurrence. The
       multiple terms are separated with a vertical bar ("|"). Compare the  following  examples  with  the  ones
       above:

           <dfn title="shoe|boot">...</dfn>
           <dfn title="shoe!!invention of|inventions!!shoe">...</dfn>

       These  two  elements  both  insert  two terms into the index. Note that the second example above combines
       subterms and multiple terms.

       It is possible to run index on a file that already has an index. The old target anchors and the old index
       will be removed before being re-generated.

OPTIONS

The following options are supported:

-t By default, hxindex adds an ID attribute to the element that contains the occurrence of a term
and also inserts an <a> element inside it with a name attribute equal to the ID. This is to
allow old browsers that ignore ID attributes, such as Netscape 4, to find the target as well.
The -t option suppresses the <a> element.

-x This option turns on XML syntax conventions: empty elements will end in /> instead of > as in
HTML. -x implies -t.

-i indexdb
hxindex can read an initial index from a file and write the merged collection of index terms
back to that file. This allows an index to span several documents. The -i option is used to
give the name of the file that contains the index.

-b base This option is useful in combination with -i to give the base URL reference of the document. By
default, hxindex will store links to occurrences in the indexdb file in the form #anchor, but
when -b is given, the links will look like base#anchor instead.

When used in combination with -n, the title attributes of the links will contain the title of
the document that contains the term. The title is inserted before the template (see option -s)
and separated from it with a comma and a space. E.g., if hxindex is called with

hxindex -i termdb -n -base myfile.html myfile.html

and the termdb already contains an entry for "foo" in in section "3.1" of a document called
"file2.html" with title "The foos", then the generated index will contain an entry such as
this:

foo, <a href="file2.html#foo"
title="The foos, section 3.1">3.1</a>

-c class[,class[,...]]
Normal index terms are recognized because they have a class of "index". The -c option adds
additional, comma-separated class names that will be considered aliases for "index". E.g., -c
instance will make sure that <span class="instance">term</span> is recognized as a term for the
index.

-n By default, the index consists of links with "#" as the anchor text. Option -n causes the link
text to consist of the section numbers of the sections in which the terms occur, falling back
to "without number" (see option -u below) if no section number could be found. Section numbers
are found by looking for the nearest preceding start tag with a class of "secno" or "no-num".
In the case of "secno", the contents of that element are taken as the section number. In the
case of "no-num" the section is assumed to have no number and hxindex will print "without
number" instead. These classes are also used by hxnum(1), so it is useful to run hxindex after
hxnum, e.g.,

hxnum myfile.html | hxindex -n >mynewfile.html

-s template
When option -n is used, the link will have a title attribute and the template determines what
it contains. The default is "section %s", where the %s is a placeholder for the section number.
In other words, the index will contain entries like this:

term, <a href="#term" title="section 7.8">7.8</a>

Some examples:

hxindex -n -s 'chapter %s'
hxindex -n -s 'part %s'
hxindex -n -s 'hoofdstuk %s' -u 'zonder nummer'

This option is only useful in combination with -n

-u phrase When option -n is used to display section numbers, references for which no section number can
be found are shown as phrase instead. The default is "??".

This option is only useful in combination with -n

-f Remove title attributes that were used for the index as well as the comments that delimit the
inserted index. This avoids that browsers display these attributes. Note that hxindex cannot be
run again on its own output if this option is used. (Mnemonic: "freeze" or "final".)

-r Do not ignore trailing punctuation when sorting index terms. E.g., if two terms are written as

hxindex will normally ignore the comma and treat them as the same term, but with -r, they are
treated as different. This affects trailing commas (,), semicolons (;), colons (:),
exclamations mark (!), question marks (?) and full stops (.). A final full stop is never
ignored if there are two or more in the term, to protect abbreviations ("B.C.") and ellipsis
("more..."). This does not affect how the index term is printed (it is always printed as it
appears in the text), only how it is compared to similar terms. (Mnemonic: "raw".)

OPERANDS

       The following operand is supported:

       file-or-URL
                 The  name  of an HTML or XML file or the URL of one. If absent, or if the file is "-", standard
                 input is read instead.

EXIT STATUS

       The following exit values are returned:

       0         Successful completion.

       >0        An error occurred in parsing the HTML file.

ENVIRONMENT

       The input is assumed to be in UTF-8, but the current locale is used to determine the sorting order of the
       index terms. I.e., hxindex looks at  the  LANG,  LC_ALL  and/or  LC_COLLATE  environment  variables.  See
       locale(1).

       To  use  a  proxy to retrieve remote files, set the environment variables http_proxy or ftp_proxy.  E.g.,
       http_proxy="http://localhost:8080/"

BUGS

       Assumes UTF-8 as input. Doesn't expand character entities (apart from the standard ones: "&amp;", "&lt;",
       "&gt" and "&quot"). Instead, pipe the input through hxunent(1) and, if needed, asc2xml(1) to  convert  it
       to UTF-8.

       Remote  files  (specified  with a URL) are currently only supported for HTTP. Password-protected files or
       files that depend on HTTP "cookies" are not handled. (You can use tools such as  curl(1)  or  wget(1)  to
       retrieve such files.)

       The accessibility of an index, even when generated with option -n, is poor.