HXCITE(1)                       HTML-XML-utils                       HXCITE(1)

NAME
       hxcite - replace bibliographic references by hyperlinks

SYNOPSIS
       hxcite [ -b base ] [ -p pattern ] [ -a auxfile ] [ -m marker ] [ -c ]
       bibfile [ file ]

DESCRIPTION
       The hxcite commands copies the file to standard output, looking for
       strings of the form [[label]].  The label may not include white space
       and the double pair of square brackets must enclose the label without
       any spaces in between. If hxcite finds the label in the bibfile, the
       string is replaced by the pattern.  The pattern can include certain
       variables. If the label is not found in bibfile, it is left unchanged.

       The default pattern replaces the string with a hyperlink, but if the -p
       option is used, the replacement can be any pattern. The input doesn't
       even have to be HTML.

       If the label is enclosed in {{...}} instead of [[...]], it is copied to
       the output unchanged and not replaced by the pattern, but the label is
       still searched in the bibfile.

OPTIONS
       The following options are supported:

       -p pattern
                 Specifies the pattern by which the string [[label]] is
                 replaced.  The pattern may include the variables %b (which is
                 replaced by the value of the -b option), %m (which is
                 replaced by the value of the -m option) and %L (which is
                 replaced by the label).  The default pattern is

                     <a href="%b#%L" rel="biblioentry">[%L]<!--{{%m%L}}--></a>


       -b base   Sets the value for the %b variable in the pattern. Typically
                 this is set to a relative or absolute URL. By default this
                 value is an empty string.

       -a auxfile
                 All labels that have been found and replaced are also written
                 to a file. This is so that hxmkbib(1) can find them and
                 create a bibliography. The default auxfile is constructed
                 from the name of the file by removing the last extension (if
                 any) and replacing it by ".aux".  If no file is given, the
                 default name is "aux.aux".

       -m marker By default, the program looks for "[[name]]", but it can be
                 made to look for "[[#name]]" where # is some string, usually
                 a symbol such as '!' or '='. This allows references to be
                 classified, e.g., "[[!name]]" for normative references and
                 "[[name]]" for non-normative references.

       -c        Causes "[[name]]" to be ignored when it occurs inside XML
                 comments ("<!--...-->"). This is useful for files where such
                 labels occur in comments, to avoid that they be expanded and
                 possibly lead to invalid output; useful also if hxcite is
                 used for non-HTML files which may contain "<!--" that are not
                 comment. Occurrences of "{{name}}" are not affected by -c.
                 (But see warning under BUGS below.)

OPERANDS
       The following operands are supported:

       bibfile   The name of a bibliographic database must be given. It must
                 be a file in refer(1) format and every entry must have at
                 least a %L field, which is used as label. (Entries without
                 such a field will be ignored.) Entries may optionally have a
                 %K line, which should contain whitespace-separated keywords.
                 Those keywords can be used to refer to the entry instead of
                 the label. Thus the foo in [[foo]] can either be the label of
                 an entry (%L line) or one of the keywords of the entry's %K
                 line.

       file      The name of the input file is optional. If absent, hxcite
                 will read from stdin. The file does not have to be an HTML
                 file, but the default pattern (see the -p option) assumes
                 HTML.

EXIT STATUS
       The following exit values are returned:

       0         Successful completion.

       > 0       An error occurred. Usually this is because a file could not
                 be opened.  Very rarely it may also be an out of memory
                 error.

VERSIONS
       March 2000: created by Bert Bos <bert@w3.org> as "cite".

       August 2008: renamed to "hxcite".

       Currently maintained by Bert Bos.

BUGS
       hxcite does not actually parse HTML or XML input and the -c option
       simply treats every occurrence of "<!--" as the start of an XML
       comment, even if it occurs inside an attribute value or a CDATA
       section. Likewise for "-->" for the end of a comment.

       There is currently no way to use numbers for references (e.g., "[1]",
       "[2]") instead of the labels ("[Lie1996]", "[UTN22]").

       hxcite requires the %L (label) field to be present in every entry in
       bibfile, which is not the case for refer(1).  hxcite does not implement
       refer's keyword search.

EXAMPLE
       The following looks for reference of the form "[[!label]]" in
       "myfile.html", skipping references that occur inside HTML comments, and
       looks up the labels in "biblio.ref". The output is written to
       "new.html" and the list of recognized labels to "myfile.aux".

           hxcite -c -m '!' biblio.ref myfile.html > new.html


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

7.x                               10 Jul 2011                        HXCITE(1)