HXCITE-MKBIB(1)

💖 hxcite-mkbib 💖 — expand references and create bibliography 🦋

okay bestie, gather round, because this is hxcite-mkbib from the HTML-XML-utils fam and it is literally the moment your boring text file becomes a whole bibliography. no cap. it's a shell script (more on that in a sec, it's giving bash) that goes through your file, finds every little [[label]] you left lying around, and swaps them for something gorgeous. 💅

---

✨ SYNOPSIS ✨

hxcite-mkbib [ -b base ] [ -p pattern ] [ -s separator ] bibfile [ file ]

---

🌸 DESCRIPTION 🌸

So here's the tea: hxcite-mkbib copies file to standard output while it hunts for strings shaped like "[[label]]", and it also looks for a template for a bibliography. The label cannot have white space in it, and that double pair of square brackets has to hug the label with zero spaces in between. no sneaky spaces allowed, bestie.

If it finds the label in the bibfile, the string gets replaced by the pattern. The pattern can have certain variables in it. And if the label is not found in bibfile? It just stays exactly as it was. left on read. 😭

The default pattern turns the string into a hyperlink, but if you use the -p option the replacement can be literally any pattern you want. The input doesn't even have to be HTML — it's flexible like that, we love that for it. 🫶

The file is made of three parts:

• preamble — Everything up to the first occurrence of %{. The preamble gets copied to the output once (with bracketed labels "[[label]]" expanded). Now listen, the % character is special, she's the main character. To get a single % in the output, you have to write two of them in the preamble (%%). Every other % followed by another letter does not get copied — instead it gets collected into a string called the "sort order." and used to sort the entries, as explained below. ✨
• template — Starts with %{L: and ends with a matching %}. The text in between gets copied as many times as there are bibliographic entries in bibfile that correspond to bracketed labels in file. Variables in the template get replaced by the corresponding field in the bibliographic entry: all occurrences of %x will be replaced by the field %x of the entry. Parts of the text may be enclosed in %{x: and %} — meaning that text should only be output if the current entry has a field x. Text enclosed in %{!x: and %} only gets output if the entry does not have a field x. And yes, both kinds of conditional sections may be nested. it's giving inception, it's giving layers. 🧚
• postamble — The text after the %} gets copied unchanged to the output, after all the bibliographic entries have been processed.

By default, bibliographic entries get copied to the output in the order of the labels in file, except that labels occurring more than once are only used once. (dedupe queen 👑) If the preamble contains occurrences of %x (where x is neither "%" nor "{") then those together determine the sort order. E.g., if the preamble contains %A%D then the entries will be sorted first on field A (author) and then on field D (date).

Here's an example of a file that creates a bibliography in HTML format:

<html>
<title>Bibliography</title>
... text with [[references]] here...
<!--%A%D sorted on author, then date -->
<dl>
%{L:
<dt id="%L">%{A:A%}%{!A:%{E:E%}%{!E:%{Q:Q%}%{!Q:-%}%}%}</dt>
<dd>%{B:"%T"
  in: %{E:%E (eds)
  %}<cite>%B.</cite>%{V: %V.%}
  %}%{J:"%T"
  in: %{E:%E (eds)
  %}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P: pp. %P.%}
  %}%{!B:%{!J:<cite>%T.</cite>
  %}%}%{I:%I.
  %}%{D:%D.
  %}%{C:%C.
  %}%{R:%R.
  %}%{S:%S.
  %}%{O:%O
  %}%{U:<a href="%U">%U</a>
  %}</dd>
%}
</dl>
</html>

This template starts with four lines of preamble, including the sort string %A%D on line 3. The sort string itself will not be output, but the rest of the comment will be. 💅

From the line %{L: to the line %} is the template. E.g., the line that starts with <dt id=... contains a complex conditional text that prints the authors (%A) if there are any, otherwise the editors (%E) if there are any, otherwise the institution that is the author (%Q), if any, and a dash otherwise. Note how the parts are nested — most of the text is inside %{!A:...%}, meaning that part will only be effective if there is no author field (%A). nesting is the vibe, honestly. 🪆

The final two lines are the postamble and will simply be copied unchanged.

A bibliographic entry that looks like this in bibfile:

%L Java
%A Gosling, James
%A Joy, Bill
%A Steele, Guy
%T The Java language specification
%D 1998
%I Addison-Wesley
%U http://java.sun.com/docs/books/jls/index.html

will be printed by the template above as:

<dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
<dd><cite>The Java language specification.</cite>
  Addison-Wesley.
  1998.
  <a href="http://java.sun.com/docs/books/jls/index.html">http://java.sun.com/docs/books/jls/index.html</a>
  </dd>

---

💅 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 will be replaced by the value of the -b option) and %L (which will be replaced by the label). The default pattern is

<a href="%b#%L" rel="biblioentry">[%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. (she's got nothing on by default, an icon of minimalism 🎀)
• -s separator — If there are multiple authors or editors in an entry, their names will be listed with a separator in between. By default the separator is "; " (i.e., a semicolon and a space). With this option the separator can be changed. (customize her, she deserves it ✨)

---

🦋 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 compared to the bracketed labels. (Entries without such a field will be ignored. sorry bestie, no %L no love 🙈)
• file — The name of the input file is optional. If absent, hxmkbib(1) will read the template from stdin.

---

⭐ DIAGNOSTICS ⭐

The following exit values are returned:

• 0 — Successful completion. 🎉 we ate.
• > 0 — An error occurred. Usually this is because a file could not be opened or because the %{ and %} pairs are not properly nested. Very rarely it may also be an out of memory error. Some of the possible error messages:
• missing ':' in pattern — hxmkbib found a %{ but the second or third letter after it was not a colon.
• no '%{' in template file — The template file is unusable, because it contains no template.
• unbalanced %{..%} in pattern — There are more %{ than %}.

bestie if you see these, check your colons and count your braces. seriously. count them. 💀

---

🔥 SEE ALSO 🔥

asc2xml(1), hxcite(1), hxmkbib(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279)

---

😭 BUGS 😭

ngl, she has some quirks. let's be real about them:

Sorting is primitive: the program doesn't parse dates or names and simply sorts "Jan 2000" under the letter "J" and "Albert Camus" under the letter "A". For the moment the only work-around is to put names in the bibfile as "Camus, Albert". (iykyk — comma first, alphabetization later 📚)

The program simply lists all authors or editors. There is no way to generate an "et. al." after the third one. The work-around is to put the "et. al." in the bibfile. Putting commas between the first authors and the word "and" before the final one is also not possible. 😔

The program doesn't try to interpret names of authors or editors and they cannot be reformatted. It is impossible to write a name that is specified as "Sartre, Jean-Paul" in the bibfile as "J. Sartre" or as "Jean-Paul Sartre" in the output. she said: what you wrote is what you get, periodt.

There is no way to suppress a period after a field if the field already ends with a period. E.g., the template "%{A:A.%}" may generate "A. Person Jr.." if the author is "A. Person Jr." The only option is to either not put periods in the bibfile or not put periods in the template. (double period era 💀)

Entries in the bibfile can only be used if they have a %L (label) field. The program cannot find entries by searching for keywords, like refer(1). no keyword search, sorry, we're label-only in this house.

hxmkbib will replace any ampersands (&) and less-than (<) and greater-than (>) signs that occur in the bibfile by their XML entities & < > on the assumption that the template is HTML/XML. This may not be appropriate for other formats. so like, watch out if you're not doing the HTML/XML thing, bestie 🫣

hxcite-mkbib is a (bash) shell script that calls hxcite(1) and hxmkbib(1), and is therefore not portable to all platforms. she's a bash girlie and she owns it.

---

and that's the whole page, bestie 💖 this one's version 7.x, dated 10 Jul 2011 — oldie but a goodie, still slaying, still sorting "Jan 2000" under J. mwah. 🎀💅✨