btparse::doc::bt_misc(3)

🦋 NAME 🦋

okay bestie, this is bt_misc from the btparse manual (third section, so like btparse::doc::bt_misc(3)) — it's the miscellaneous BibTeX-flavoured string-processing utilities 💅

---

✨ SYNOPSIS ✨

void bt_purify_string (char * string, btshort options);
void bt_change_case (char transform, char * string, btshort options);

---

💖 DESCRIPTION 💖

Two little functions, both living their best life in here. Let's go 🫶

🧼 bt_purify_string()

void bt_purify_string (char * string, btshort options);

So this one “purifies” a “string” the BibTeX way — it's usually the move when you're generating sort keys, iykyk 🔑 The string gets modified in-place, no copy, no take-backs. As for options? bestie it's currently unused — just set it to zero for future compatibility and keep it pushing 🙈

Purification is literally: copy the alphanumeric characters, convert hyphens and ties to a space, copy the spaces, and skip (almost) everything else. Almost.

Why almost? Because “special characters” (the ones used for accented and non-English letters) get handled specially. Reminder, because this matters: a BibTeX special character is any brace-group that starts at brace-depth zero whose first character is a backslash 💀

For instance, this string:

{\foo bar}Herr M\"uller went from {P{\r r}erov} to {\AA}rhus

contains exactly two special characters: {\foo bar} and \AA. Neither the \"u nor the \r r are special characters, because they are not at the right brace depth. depth is everything, periodt

So how are special characters handled? Here's the tea ☕ if the control sequence (that's the TeX command following the backslash) is recognized as one of LaTeX's “foreign letters” (\oe, \ae, \o, \l, \ae, \ss, plus uppercase versions), then it gets converted to a reasonable English approximation by stripping the backslash and converting the second character (if any) to lowercase. So {\AA} up there would become simply Aa 🌸

All other control sequences inside a special character get stripped, and so do all non-alphabetic characters.

So for example, that string above, after purification, becomes:

barHerr Muller went from Pr rerov to Aarhus

ngl, something has obviously gone wrong with the word P{\r r}erov (a town in the Czech Republic, no shade to it 🍓). That accented r should be a special character, starting at brace-depth zero. If the original string were instead:

{\foo bar}Herr M\"uller went from P{\r r}erov to {\AA}rhus

then the purified result would be way more sensible:

barHerr Muller went from Prerov to Aarhus

okay now notice the use of a “nonsense” special character {\foo bar} — this trick is often used to put certain text in a string solely for generating sort keys. The text then gets ignored when the document is processed by TeX (as long as \foo is defined as a no-op TeX macro) ✨

but bestie, this assumes of course that the output is eventually processed by TeX. If not, then this trick will backfire on you 😭💀

Also, bt_purify_string() is adequate for generating sort keys when you want to sort according to English-language conventions. But to follow the conventions of other languages? a more sophisticated approach will be needed — hopefully, future versions of btparse will address this deficiency 🙏

🔠 bt_change_case()

void bt_change_case (char transform, char * string, btshort options);

This one converts a string to lowercase, uppercase, or “non-book title capitalization”, with special attention paid to BibTeX special characters and other brace-groups 👑

The form of conversion is picked by that single character transform:

• 'u' — convert to uppercase
• 'l' — convert to lowercase
• 't' — convert to “title capitalization”

string is modified in-place, and options is currently unused — set it to zero for future compatibility, same deal as before 🙈

Lowercase and uppercase conversion are obvious, with the proviso that text in braces is treated differently (explained below 👇). Title capitalization simply means that everything is converted to lowercase, except the first letter of the first word, and words immediately following a colon or sentence-ending punctuation. For instance:

Flying Squirrels: Their Peculiar Habits. Part One

would be converted to:

Flying squirrels: Their peculiar habits. Part one

Now, text within braces is handled as follows. First, in a “special character” (see above for the definition, bestie), control sequences that constitute one of LaTeX's non-English letters are converted appropriately — e.g., when converting to lowercase, \AE becomes \ae ✨ Any other control sequence in a special character (including accents) is preserved, and all text in a special character, regardless of depth and punctuation, is converted to lowercase or uppercase. (For “title capitalization,” all text in a special character is converted to lowercase.)

Brace groups that are not special characters are left completely untouched: neither text nor control sequences within non-special-character braces are touched. not a single hair on their head 🎀

For example, the string:

A Guide to \LaTeXe: Document Preparation ...

would, when transform is 't' (title capitalization), be converted to:

A guide to \latexe: Document preparation ...

which is probably not the desired result 😭 A better attempt is:

A Guide to {\LaTeXe}: Document Preparation ...

which becomes:

A guide to {\LaTeXe}: Document preparation ...

However — if you go back and re-read the description of bt_purify_string(), you'll discover that {\LaTeXe} here is a special character, but not a non-English letter: thus, the control sequence is stripped. So a sort key generated from this title would be:

A Guide to  Document Preparation

...oops! 🙈 The right solution (and this applies to any title with a TeX command that becomes actual text) is to bury the control sequence at brace-depth two:

A Guide to {{\LaTeXe}}: Document Preparation ...

---

🌈 SEE ALSO 🌈

btparse

---

👑 AUTHOR 👑

Greg Ward <gward@python.net>

---

and that's the whole page, bestie 💖 btparse, version 0.91, dated 2025-01-31 — shoutout to btparse::doc::bt_misc(3) for having us, mwah 💅✨🦋