NAME

       mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc, mchars_spec2cp, mchars_spec2str, mchars_uc2str
       — character table for mandoc

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

       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() initializes a static struct ohash 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  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 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), ohash_init(3), mandoc_char(7), roff(7)

HISTORY

       These functions and their predecessors have been available since the following 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>

Debian                                            July 7, 2016                                   MCHARS_ALLOC(3)