packages icon



 HXINDEX(1)                          5.x                          HXINDEX(1)
 HTML-XML-utils                                               HTML-XML-utils

                                 21 Nov 2008



 NAME
      hxindex - insert an index into an HTML document

 SYNOPSIS
      hxindex [ -t ] [ -x ] [ -n ] [ -f ] [ -r ] [ -c classes ] [ -b base ] [
      -i indexdb ] [--] [ 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>



                                    - 1 -         Formatted:  March 28, 2024






 HXINDEX(1)                          5.x                          HXINDEX(1)
 HTML-XML-utils                                               HTML-XML-utils

                                 21 Nov 2008



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

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



                                    - 2 -         Formatted:  March 28, 2024






 HXINDEX(1)                          5.x                          HXINDEX(1)
 HTML-XML-utils                                               HTML-XML-utils

                                 21 Nov 2008



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

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

                    <dfn>foo,</dfn>... <span class=index>foo</span>

                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.



                                    - 3 -         Formatted:  March 28, 2024






 HXINDEX(1)                          5.x                          HXINDEX(1)
 HTML-XML-utils                                               HTML-XML-utils

                                 21 Nov 2008



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

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






























                                    - 4 -         Formatted:  March 28, 2024