HXREF(1)

✨ NAME ✨

hxref — generate cross-references inside and between HTML files 💖

okay bestie, this is from the HTML-XML-utils crew and it's literally the girl who remembers who said what and links everyone together at the party. let's go 🫶

🌸 SYNOPSIS 🌸

hxref [ -x ] [ -l ] [ -b base ] [ -i index ] [ -- ] [ input [ output ] ]

💅 DESCRIPTION 💅

so what hxref does is it takes inline elements and links them up to DFN elements that have the exact same content. slay. it also adds ID attributes wherever they're needed, because a link needs somewhere to land, obviously.

and if the content of a DFN (or any other element, no gatekeeping) isn't suitable for that, you can use the TITLE attribute to hand it the term it should use for comparisons instead. iconic.

here's the example, look at her:

<p>A <dfn>b-box</dfn> is defined to be...
<p>For every b there is a <em>b-box</em>...

and the output of hxref will be similar to this:

<p>A <dfn id="b-box">b-box</dfn> is defined to be...
<p>For every b there is a <a href="#b-box"><em>b-box</em></a>...

see how the second one got wrapped in an <a href="#b-box">? the way that it just knew. ✨

🎀 OPTIONS 🎀

The following options are supported:

• -x — use XML conventions, bestie: empty elements get written with a slash at the end, like <IMG /> 💀
• -b base — sets the prefix for the generated URLs. by default base is empty, which gives you URLs like #b-box up there. but if you set base to, e.g., "http://xyz/", the URLs will look like "http://xyz/#b-box". obsessed.
• -i index — tells hxref to read terms from a database file before it goes looking for them in the document, and then afterwards store the terms it found in that same file. DFN elements in the document override the terms found in index. this is the whole "let my files talk to each other" thing: it lets you run hxref multiple times on different files so they can refer to each other. ngl it may be necessary to run the commands twice to resolve all cross-references. 🙈
• -l — try to use language-specific info to match instances to their definitions. currently only English is supported, and the only rules applied are: search without a final "s" ("trees" matches "tree"), without a final "es" ("bosses" matches "boss"), and with a "y" replacing a final "ies" ("bounties" matches "bounty"). hxref figures out the language from the "lang" and "xml:lang" attributes in the document. lowkey clever. 🌈

🦋 OPERANDS 🦋

The following operands are supported:

• input — the name of an HTML file. if it's absent, standard input gets read instead. the special name "-" also means standard input. and yes, the input may be an URL. 💜
• output — the file to write to. if it's absent, standard output is used. this one may not be a URL, sorry babe. 🚫

💀 DIAGNOSTICS 💀

The following exit values are returned:

• 0 — successful completion. we love a clean run. 👑
• > 0 — an error occurred in the parsing of the HTML file. hxref will try to correct the error and produce output anyway, because she's a tryer. 😭

🔥 SEE ALSO 🔥

asc2xml(1), hxindex(1), hxnormalize(1), hxnum(1), hxtoc(1), xml2asc(1)

go read the whole friend group, they're all iconic. 🫶

🍓 BUGS 🍓

bestie, gather round, here's the fine print:

• the error recovery for incorrect HTML is primitive. fr fr, don't come for her.
• the program generates ID attributes, but it doesn't generate <a name=...> tags, so the links only work in browsers that recognize ID attributes. no cap, that's a real limitation.
• the rules for matching English plurals are primitive. no dictionary is used. e.g., "bees" will be considered a plural of "be". 💀 she's doing her best.
• there is currently no way to set the default language for a document for when the root element has no "lang" or "xml:lang" attribute. 😭
• hxref tries first to generate "readable" ID attributes, by forming the ID out of the letters and digits found in the content of the element, and falls back to generating arbitrary IDs if it doesn't find enough. however, the algorithm in this version is primitive and only gives reasonable results for ASCII letters and digits. so keep it ASCII, babe. ✨

this whole thing lives in the HTML-XML-utils, version 7.x, dated 10 Jul 2011. mwah, take care of each other, and go cross-reference something cute 💖