Provided by: html-xml-utils_6.5-1_amd64 bug

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

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

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

SEE ALSO

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