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)