HXMKBIB(1)

✨ HXMKBIB(1) ✨

okay bestie, meet hxmkbib 💖 she hangs out with the HTML-XML-utils crew 👑 and she will literally build you an entire bibliography out of a template. no cap. it's giving "librarian but make it fashion" 💅

---

🎀 NAME 🎀

hxmkbib — create bibliography from a template 🦋

---

🌈 SYNOPSIS 🌈

hxmkbib [ -s separator ] [ -a auxfile ] [ -n maxauthors ] [ -r moreauthors ] bibfile [ templatefile ]

---

💜 DESCRIPTION 💜

so here's the vibe, bestie: hxmkbib reads a list of bibliographic keys (aka labels) out of auxfile, goes hunting for the matching entries in bibfile, and then builds you a whole bibliography using templatefile as the model ✨

the auxfile might've been made by hxcite(1), iykyk. it's just labels, one per line. and bibfile is a refer(1) style database. hxmkbib looks for entries whose %L field equals a key in the auxfile 🔍

the templatefile is made of three parts, and honestly all three are main characters:

🌸 preamble 🌸

the preamble is everything up to the first time %{ shows up. it gets copied to the output totally unchanged — except for any occurrences of %. to get a single % in the output, you gotta write two of them in the preamble (%%) 🙈. every other occurrence of % followed by another letter does not get copied — instead those get collected into a string called the "sort order." and used to sort the entries, as explained down below ⬇️

🦋 template 🦋

the 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 keys in auxfile 🎀

variables in the template get replaced by the matching field from the bibliographic entry: every occurrence of %x gets swapped for the field %x of the entry. parts of the text can be wrapped in %{x: and %}, which means only output the text in between if the current entry actually has a field x. and text wrapped in %{!x: and %} only gets output if the entry does not have a field x 🙅‍♀️ both kinds of conditional sections can be nested too, like lil matryoshka dolls 🪆

💫 postamble 💫

the text after the %} gets copied unchanged to the output, once all the bibliographic entries have been processed. periodt 💅

---

by default, bibliographic entries land in the output in the order of the keys in auxfile, except keys that show up more than once only get used once (we don't do duplicates here 🙈). but if the preamble contains occurrences of %x (where x is neither "%" nor "{"), then those together decide the sort order 🔥 e.g., if the preamble contains %A%D then the entries get sorted first on field A (author) and then on field D (date).

here's an example template file that creates a bibliography in HTML format, she's iconic honestly ✨:

<html>
<title>Bibliography</title>
<!--%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., that line starting with <dt id=... has a super 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 😭 notice how the parts are nested. most of the text is inside %{!A:...%}, meaning that part only kicks in if there's no author field (%A) 💅

the final two lines are the postamble and get copied unchanged, simple as that 🫶

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, bestie:

• -a auxfile — the file that contains the list of keys (labels) you want bibliographic entries printed for. if you skip this option, the name of the file gets formed from the templatefile argument by removing the last extension and adding .aux 🎀. and if no templatefile is given either, the default auxfile is aux.aux 🙈
• -s separator — if there are multiple authors or editors in an entry, their names get listed with a separator in between. by default that separator is "; " (i.e., a semicolon and a space). with this option you can change it ✨
• -n maxauthors — if there are more than maxauthors authors in an entry, only the first author gets printed and the others get replaced by the moreauthors string 😭. the default is 3.
• -r moreauthors — the string to print when there are more than maxauthors authors. the default is "et al." 💅

---

🧚 OPERANDS 🧚

the following operands are supported:

• bibfile — the name of a bibliographic database, and you must give it. it has to be a file in refer(1) format and every entry must have at least a %L field, which is used as the key 🔑 (entries without such a field get ignored, rip 💀)
• templatefile — the name of the input file, and this one's optional. if it's absent, hxmkbib will read the template from stdin 🌸

---

🩺 DIAGNOSTICS 🩺

the following exit values are returned:

• 0 — successful completion, slay 👑
• > 0 — an error occurred 😭 usually this is because a file couldn't be opened or because the %{ and %} pairs aren't 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 wasn't a colon 🙅‍♀️
• no '%{' in template file — the template file is unusable because it contains no template 💀
• unbalanced %{..%} in pattern — there are more %{ than %} 😵‍💫

---

👀 SEE ALSO 👀

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

---

💀 BUGS 💀

bestie, read these before you get your hopes up. she's cute but she has limits.

• sorting is primitive, ngl: 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".
• 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 💀
• 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.
• 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) does 🫠
• 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.

---

okay that's the whole tea, bestie 🍓 this lil guide was brought to you by version 7.x, dated 10 Jul 2011 — yeah she's a vintage queen but she still eats 💅💖 go forth and cite responsibly ✨