plucky (3) mchars_alloc.3.gz

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>