HXCITE
Section: HTML-XML-utils (1)
Updated: 10 Jul 2011
Index
Return to Main Contents
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 occurence 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)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- OPERANDS
-
- EXIT STATUS
-
- VERSIONS
-
- BUGS
-
- EXAMPLE
-
- SEE ALSO
-