NAME
mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc, mchars_spec2cp, mchars_spec2str − character table for mandoc
LIBRARY
Mandoc Macro Compiler Library (libmandoc, −lmandoc)
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 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.
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 representation. The length of the representation is returned in rsz. In many cases, the meaning of such ASCII representations is not quite obvious, 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 ALSO
mandoc(1), mandoc_escape(3), mandoc_char(7), roff(7)
HISTORY
These functions and their predecessors have been available since the following mandoc versions:
AUTHORS
Kristaps
Dzonsons <kristaps [AT] bsd.lv>
Ingo Schwarze <schwarze [AT] openbsd.org>