1MCHARS_ALLOC(3)          BSD Library Functions Manual          MCHARS_ALLOC(3)
2

NAME

4     mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc,
5     mchars_spec2cp, mchars_spec2str, mchars_uc2str — character table for man‐
6     doc
7

SYNOPSIS

9     #include <sys/types.h>
10     #include <mandoc.h>
11
12     void
13     mchars_alloc(void);
14
15     void
16     mchars_free(void);
17
18     char
19     mchars_num2char(const char *decimal, size_t sz);
20
21     int
22     mchars_num2uc(const char *hexadecimal, size_t sz);
23
24     int
25     mchars_spec2cp(const char *name, size_t sz);
26
27     const char *
28     mchars_spec2str(const char *name, size_t sz, size_t *rsz);
29
30     const char *
31     mchars_uc2str(int codepoint);
32

DESCRIPTION

34     These functions translate Unicode character numbers and roff(7) character
35     names into glyphs.  See mandoc_char(7) for a list of roff(7) special
36     characters.  These functions are intended for external use by programs
37     formatting mdoc(7) and man(7) pages for output, for example the mandoc(1)
38     output formatter modules and makewhatis(8).  The decimal, hexadecimal,
39     name, and size input arguments are usually obtained from the
40     mandoc_escape(3) parser function.
41
42     The function mchars_num2char() converts a decimal string representation
43     of a character number consisting of sz digits into a printable ASCII
44     character.  If the input string is non-numeric or does not represent a
45     printable ASCII character, the NUL character (‘\0’) is returned.  For
46     example, the mandoc(1) -Tascii, -Tutf8, and -Thtml output modules use
47     this function to render roff(7) \N escape sequences.
48
49     The function mchars_num2uc() converts a hexadecimal string representation
50     of a Unicode codepoint consisting of sz digits into an integer represen‐
51     tation.  If the input string is non-numeric or represents an ASCII char‐
52     acter, the NUL character (‘\0’) is returned.  For example, the mandoc(1)
53     -Tutf8 and -Thtml output modules use this function to render roff(7)
54     \[uXXXX] and \C'uXXXX' escape sequences.
55
56     The function mchars_alloc() initializes a static struct ohash object for
57     subsequent use by the following two lookup functions.  When no longer
58     needed, this object can be destroyed with mchars_free().
59
60     The function mchars_spec2cp() looks up a roff(7) special character name
61     consisting of sz characters and returns the corresponding Unicode code‐
62     point.  If the name is not recognized, -1 is returned.  For example, the
63     mandoc(1) -Tutf8 and -Thtml output modules use this function to render
64     roff(7) \[name] and \C'name' escape sequences.
65
66     The function mchars_spec2str() looks up a roff(7) special character name
67     consisting of sz characters and returns an ASCII string representation.
68     The length of the representation is returned in rsz.  In many cases, the
69     meaning of such ASCII representations is not quite obvious, so using
70     roff(7) special characters in documents intended for ASCII rendering is
71     usually a bad idea.  If the name is not recognized, NULL is returned.
72     For example, makewhatis(8) and the mandoc(1) -Tascii output module use
73     this function to render roff(7) \[name] and \C'name' escape sequences.
74
75     The function mchars_uc2str() performs a reverse lookup of the Unicode
76     codepoint and returns an ASCII string representation, or the string "<?>"
77     if none is available.
78

FILES

80     These funtions are implemented in the file chars.c.
81

SEE ALSO

83     mandoc(1), mandoc_escape(3), ohash_init(3), mandoc_char(7), roff(7)
84

HISTORY

86     These functions and their predecessors have been available since the fol‐
87     lowing mandoc versions:
88
89     function             since     predecessor         since
90     mchars_alloc()       1.11.3    ascii2htab()        1.5.3
91     mchars_free()        1.11.2    asciifree()         1.6.0
92     mchars_num2char()    1.11.2    chars_num2char()    1.10.10
93     mchars_num2uc()      1.11.3    —                   —
94     mchars_spec2cp()     1.11.2    chars_spec2cp()     1.10.5
95     mchars_spec2str()    1.11.2    a2ascii()           1.5.3
96     mchars_uc2str()      1.13.2    —                   —
97

AUTHORS

99     Kristaps Dzonsons <kristaps@bsd.lv>
100     Ingo Schwarze <schwarze@openbsd.org>
101
102BSD                              June 20, 2019                             BSD
Impressum