HXCITE(1)

💖 HXCITE(1) 💖

okay bestie, welcome to the hxcite page — it's part of the HTML-XML-utils crew, manual section 1, and it's here to make your bibliographic references pop off. hyperlinks, slay ✨

---

✨ NAME ✨

hxcite — swap out bibliographic references for hyperlinks, no cap 🎀

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

so the hxcite command literally just copies the file to standard output, but while it's doing that it's on the lookout for strings that look like [[label]]. the label cannot have white space in it, and both pairs of square brackets have to hug the label with no spaces in between, ok? like, that's the vibe check it's running.

if hxcite finds that label in the bibfile, the whole string gets replaced by the pattern. 👑 the pattern can have certain variables in it. but if the label is not found in bibfile? it's just left exactly how it was. no drama.

the default pattern turns the string into a hyperlink, but the second you use the -p option, the replacement can be any pattern you want. the input doesn't even have to be HTML. it's giving versatile 💅

oh and here's a cute little twist: if the label is wrapped in {{...}} instead of [[...]], it gets copied to the output unchanged and is not replaced by the pattern — but bestie, the label is still searched for in the bibfile. 🧚

---

💅 OPTIONS 💅

here's what you can throw at it:

• -p pattern — sets the pattern that replaces the string [[label]]. the pattern may include the variables %b (swapped for whatever the -b option's value is), %m (swapped for the -m option's value) and %L (swapped for the label). the default pattern is:

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

• -b base — sets the value of the %b variable in the pattern. typically you'd set this to a relative or absolute URL. by default this value is an empty string. 🙈
• -a auxfile — every label that got found and replaced also gets written to a file, so that hxmkbib(1) can find them and build you a bibliography. 📚 the default auxfile is made from the name of the file by chopping off the last extension (if there is one) and replacing it with ".aux". and if no file is given at all, the default name is "aux.aux".
• -m marker — by default the program looks for "[[name]]", but you can make it look for "[[#name]]" where # is some string, usually a symbol like '!' or '='. this lets you classify references, e.g. "[[!name]]" for normative references and "[[name]]" for non-normative ones. iconic sorting behavior ⭐
• -c — makes "[[name]]" get ignored when it shows up inside XML comments ("<!--...-->"). super useful for files where those labels live in comments, so they don't get expanded and maybe produce invalid output — also useful if hxcite is being used on non-HTML files that happen to contain "<!--" that isn't actually a comment. occurrences of "{{name}}" are not affected by -c. (but peep the warning under BUGS below 👀)

---

🎀 OPERANDS 🎀

these are the operands it supports:

• bibfile — you must give the name of a bibliographic database. it has to be a file in refer(1) format and every entry needs at least a %L field, which is used as the label. (entries without that field just get ignored, rip 🙈) entries can 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. so the foo in [[foo]] can either be the label of an entry (the %L line) or one of the keywords from the entry's %K line. 💫
• file — the input file name is optional! if you don't give one, hxcite reads from stdin. the file doesn't have to be HTML, but the default pattern (see the -p option) does assume HTML. 🌈

---

🔥 EXIT STATUS 🔥

here's what the exit values mean:

• 0 — successful completion, we ate 💅
• > 0 — an error happened. usually it's because a file couldn't be opened. very rarely it could 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 💀

okay so listen, 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 shows up inside an attribute value or a CDATA section. same deal for "-->" as the end of a comment. 🚨

there's currently no way to use numbers for references (like "[1]", "[2]") instead of the labels ("[Lie1996]", "[UTN22]"). 😔

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

---

⭐ EXAMPLE ⭐

the following looks for references of the form "[[!label]]" in "myfile.html", skips references that occur inside HTML comments, and looks up the labels in "biblio.ref". the output goes to "new.html" and the list of recognized labels goes 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)

---

and that's the whole page, bestie! this one's version 7.x, dated 10 Jul 2011 — so go forth, cite responsibly, and let hxcite do the heavy lifting. mwah 💖✨