Man Linux: Main Page and Category List


       hxindex - insert an index into an HTML document


       hxindex  [  -t  ]  [ -x ] [ -n ] [ -f ] [ -c classes ] [ -b base ] [ -i
       indexdb ] [--] [ file-or-URL ]


       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


       or between two comments of the form


       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-

       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-


       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

       -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

       -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 "#" only 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  a  "#"
                 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

       -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".)


       The following operand is supported:

                 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.


       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


       The following exit values are returned:

       0         Successful completion.

       >0        An error occurred in parsing the HTML file.


       asc2xml(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1),
       xml2asc(1), locale(1), UTF-8 (RFC 2279)


       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.