MCHARS_ALLOC(3)

💖 MCHARS_ALLOC 💖 — the character table for mandoc, bestie

okay so this is a page from the Library Functions Manual, and it's all about the little glyph-translation squad that lives in mandoc. Pull up a chair, we're decoding characters together 🦋

✨ NAME ✨

mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc, mchars_spec2cp, mchars_spec2str, mchars_uc2str — the character table for mandoc, and yes that's a whole friend group, they come as a set 💅

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <mandoc.h>

void
mchars_alloc(void);

void
mchars_free(void);

char
mchars_num2char(const char *decimal, size_t sz);

int
mchars_num2uc(const char *hexadecimal, size_t sz);

int
mchars_spec2cp(const char *name, size_t sz);

const char *
mchars_spec2str(const char *name, size_t sz, size_t *rsz);

const char *
mchars_uc2str(int codepoint);

🎀 DESCRIPTION 🎀

So here's the vibe: these functions take Unicode character numbers and roff(7) character names and turn them into actual glyphs. If you want the full list of roff(7) special characters, go look at mandoc_char(7) — she has the receipts 📜

These functions are meant for external use by programs that format mdoc(7) and man(7) pages for output. We're talking the mandoc(1) output formatter modules, and makewhatis(8), stuff like that. And the decimal, hexadecimal, name, and sz input arguments? They usually come straight from the mandoc_escape(3) parser function. Teamwork, honestly 🫶

mchars_num2char() — takes a decimal string representation of a character number that's sz digits long, and converts it into a printable ASCII character. Now listen: if the input string is non-numeric, or it doesn't represent a printable ASCII character, you get the NUL character ('\0') back. That's the deal. For example, the mandoc(1) -Tascii, -Tutf8, and -Thtml output modules use this function to render roff(7) \N escape sequences ✨

mchars_num2uc() — takes a hexadecimal string representation of a Unicode codepoint that's sz digits long, and converts it into an integer representation. If the input string is non-numeric or represents an ASCII character, the NUL character ('\0') is returned. For example, the mandoc(1) -Tutf8 and -Thtml output modules use this function to render roff(7) \[uXXXX] and \C'uXXXX' escape sequences 🔥

mchars_alloc() — initializes a static struct ohash object for subsequent use by the following two lookup functions. When you don't need it anymore, that object can be destroyed with mchars_free(). Clean up after yourself, bestie, it's giving self-care 🧖

mchars_spec2cp() — looks up a roff(7) special character name that's sz characters long and returns the corresponding Unicode codepoint. If the name isn't recognized? -1. That's it, that's the answer. For example, the mandoc(1) -Tutf8 and -Thtml output modules use this function to render roff(7) \[name] and \C'name' escape sequences 💜

mchars_spec2str() — looks up a roff(7) special character name that's sz characters long and returns an ASCII string representation. The length of that representation gets handed back to you in rsz. And okay, real talk: in a lot of cases the meaning of these ASCII representations is not quite obvious, so using roff(7) special characters in documents intended for ASCII rendering is usually a bad idea. Noted, we've all been there 😭 If the name isn't recognized, NULL is returned. For example, makewhatis(8) and the mandoc(1) -Tascii output module use this function to render roff(7) \[name] and \C'name' escape sequences 🌈

mchars_uc2str() — does a reverse lookup of the Unicode codepoint and returns an ASCII string representation, or the string "<?>" if none is available. She's doing her best, and honestly? Iconic.

💀 FILES 💀

These functions are implemented in the file chars.c.

👑 SEE ALSO 👑

mandoc(1), mandoc_escape(3), ohash_init(3), mandoc_char(7), roff(7)

⭐ HISTORY ⭐

These functions and their predecessors have been available since the following mandoc versions — so basically, a whole family tree 🌳

• mchars_alloc() — since 1.11.3, predecessor ascii2htab() since 1.5.3
• mchars_free() — since 1.11.2, predecessor asciifree() since 1.6.0
• mchars_num2char() — since 1.11.2, predecessor chars_num2char() since 1.10.10
• mchars_num2uc() — since 1.11.3, predecessor — since —
• mchars_spec2cp() — since 1.11.2, predecessor chars_spec2cp() since 1.10.5
• mchars_spec2str() — since 1.11.2, predecessor a2ascii() since 1.5.3
• mchars_uc2str() — since 1.13.2, predecessor — since —

💖 AUTHORS 💖

• Kristaps Dzonsons <kristaps@bsd.lv>
• Ingo Schwarze <schwarze@openbsd.org>

and that's the whole page, bestie 🎀 shoutout to the Debian crew — this one's dated July 7, 2016, and yeah it still says MCHARS_ALLOC(3) at the bottom like a little signature. periodt 💅✨