DragonFly On-Line Manual Pages

MCHARS_ALLOC(3)       DragonFly Library Functions Manual       MCHARS_ALLOC(3)

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:

     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>

DragonFly 6.5-DEVELOPMENT      October 26, 2014      DragonFly 6.5-DEVELOPMENT