MCHARS_ALLOC(3) BSD Library Functions Manual MCHARS_ALLOC(3)NAME
mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc,
mchars_spec2cp, mchars_spec2str — character table for mandoc
LIBRARY
library “libmandoc”
SYNOPSIS
#include <sys/types.h>
#include <mandoc.h>
struct mchars *
mchars_alloc(void);
void
mchars_free(struct mchars *table);
char
mchars_num2char(const char *decimal, size_t sz);
int
mchars_num2uc(const char *hexadecimal, size_t sz);
int
mchars_spec2cp(const struct mchars *table, const char *name, size_t sz);
const char *
mchars_spec2str(const struct mchars *table, const char *name, size_t sz,
size_t *rsz);
const char *
mchars_uc2str(int codepoint);
DESCRIPTION
These functions translate Unicode character numbers and roff(7) character
names into glyphs. See mandoc_char(7) for a list of roff(7) special
characters. These functions are intended for external use by programs
formatting mdoc(7) and man(7) pages for output, for example the mandoc(1)
output formatter modules and makewhatis(8). The decimal, hexadecimal,
name, and size input arguments are usually obtained from the
mandoc_escape(3) parser function.
The function mchars_num2char() converts a decimal string representation
of a character number consisting of sz digits into a printable ASCII
character. If the input string is non-numeric or does not represent a
printable ASCII character, the NUL character (‘\0’) is returned. For
example, the mandoc(1)-Tascii, -Tutf8, and -Thtml output modules use
this function to render roff(7) \N escape sequences.
The function mchars_num2uc() converts a hexadecimal string representation
of a Unicode codepoint consisting of sz digits into an integer represen‐
tation. If the input string is non-numeric or represents an ASCII char‐
acter, 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.
The function mchars_alloc() allocates an opaque struct mchars * table
object for subsequent use by the following two lookup functions. When no
longer needed, this object can be destroyed with mchars_free().
The function mchars_spec2cp() looks up a roff(7) special character name
consisting of sz characters in the table and returns the corresponding
Unicode codepoint. If the name is not recognized, -1 is returned. For
example, the mandoc(1)-Tutf8 and -Thtml output modules use this function
to render roff(7) \[name] and \C'name' escape sequences.
The function mchars_spec2str() looks up a roff(7) special character name
consisting of sz characters in the table and returns an ASCII string rep‐
resentation. The length of the representation is returned in rsz. In
many cases, the meaning of such ASCII representations is not quite obvi‐
ous, so using roff(7) special characters in documents intended for ASCII
rendering is usually a bad idea. If the name is not 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.
The function mchars_uc2str() performs a reverse lookup of the Unicode
codepoint and returns an ASCII string representation, or the string "<?>"
if none is available.
FILES
These funtions are implemented in the file chars.c.
SEE ALSOmandoc(1), mandoc_escape(3), mandoc_char(7), roff(7)HISTORY
These functions and their predecessors have been available since the fol‐
lowing mandoc versions:
function since predecessor since
mchars_alloc() 1.11.3 ascii2htab() 1.5.3
mchars_free() 1.11.2 asciifree() 1.6.0
mchars_num2char() 1.11.2 chars_num2char() 1.10.10
mchars_num2uc() 1.11.3 — —
mchars_spec2cp() 1.11.2 chars_spec2cp() 1.10.5
mchars_spec2str() 1.11.2 a2ascii() 1.5.3
mchars_uc2str() 1.13.2 — —
AUTHORS
Kristaps Dzonsons ⟨kristaps@bsd.lv⟩
Ingo Schwarze ⟨schwarze@openbsd.org⟩
BSD April 29, 2024 BSD
