---
name: "hxcite"
section: "1"
platform: "linux"
package: "html-xml-utils"
version: "8.8-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hxcite"
---

# hxcite(1)

replace bibliographic references by hyperlinks

## 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)](/hxmkbib/1.md) 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)](/refer/1.md) 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)](/refer/1.md). **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)](/asc2xml/1.md), [**refer**(1)](/refer/1.md), [**hxmkbib**(1)](/hxmkbib/1.md), [**hxnormalize**(1)](/hxnormalize/1.md), [**hxnum**(1)](/hxnum/1.md), [**hxprune**(1)](/hxprune/1.md), [**hxtoc**(1)](/hxtoc/1.md), [**hxunent**(1)](/hxunent/1.md), [**xml2asc**(1)](/xml2asc/1.md), **UTF-8** (RFC 2279)