| blob | 8c3f853492f24ac8a7572c6d217da5ab8132f2c7 |
1 .\" $Id: mchars_alloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate: August 5 2014 $
18 .Dt MCHARS_ALLOC 3
19 .Os
20 .Sh NAME
21 .Nm mchars_alloc ,
22 .Nm mchars_free ,
23 .Nm mchars_num2char ,
24 .Nm mchars_num2uc ,
25 .Nm mchars_spec2cp ,
26 .Nm mchars_spec2str
27 .Nd character table for mandoc
28 .Sh LIBRARY
29 .Lb libmandoc
30 .Sh SYNOPSIS
31 .In sys/types.h
32 .In mandoc.h
33 .Ft "struct mchars *"
34 .Fn mchars_alloc "void"
35 .Ft void
36 .Fo mchars_free
37 .Fa "struct mchars *table"
38 .Fc
39 .Ft char
40 .Fo mchars_num2char
41 .Fa "const char *decimal"
42 .Fa "size_t sz"
43 .Fc
44 .Ft int
45 .Fo mchars_num2uc
46 .Fa "const char *hexadecimal"
47 .Fa "size_t sz"
48 .Fc
49 .Ft int
50 .Fo mchars_spec2cp
51 .Fa "const struct mchars *table"
52 .Fa "const char *name"
53 .Fa "size_t sz"
54 .Fc
55 .Ft "const char *"
56 .Fo mchars_spec2str
57 .Fa "const struct mchars *table"
58 .Fa "const char *name"
59 .Fa "size_t sz"
60 .Fa "size_t *rsz"
61 .Fc
62 .Sh DESCRIPTION
63 These functions translate Unicode character numbers and
64 .Xr roff 7
65 character names into glyphs.
66 See
67 .Xr mandoc_char 7
68 for a list of
69 .Xr roff 7
70 special characters.
71 These functions are intended for external use by programs formatting
72 .Xr mdoc 7
73 and
74 .Xr man 7
75 pages for output, for example the
76 .Xr mandoc 1
77 output formatter modules and
78 .Xr makewhatis 8 .
79 The
80 .Fa decimal ,
81 .Fa hexadecimal ,
82 .Fa name ,
83 and
84 .Fa size
85 input arguments are usually obtained from the
86 .Xr mandoc_escape 3
87 parser function.
88 .Pp
89 The function
90 .Fn mchars_num2char
91 converts a
92 .Fa decimal
93 string representation of a character number consisting of
94 .Fa sz
95 digits into a printable ASCII character.
96 If the input string is non-numeric or does not represent a printable
97 ASCII character, the NUL character
98 .Pq Sq \e0
99 is returned.
100 For example, the
101 .Xr mandoc 1
102 .Fl Tascii ,
103 .Fl Tutf8 ,
104 and
105 .Fl Thtml
106 output modules use this function to render
107 .Xr roff 7
108 .Ic \eN
109 escape sequences.
110 .Pp
111 The function
112 .Fn mchars_num2uc
113 converts a
114 .Fa hexadecimal
115 string representation of a Unicode codepoint consisting of
116 .Fa sz
117 digits into an integer representation.
118 If the input string is non-numeric or represents an ASCII character,
119 the NUL character
120 .Pq Sq \e0
121 is returned.
122 For example, the
123 .Xr mandoc 1
124 .Fl Tutf8
125 and
126 .Fl Thtml
127 output modules use this function to render
128 .Xr roff 7
129 .Ic \e[u Ns Ar XXXX Ns Ic \&]
130 and
131 .Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq
132 escape sequences.
133 .Pp
134 The function
135 .Fn mchars_alloc
136 allocates an opaque
137 .Vt "struct mchars *"
138 table object for subsequent use by the following two lookup functions.
139 When no longer needed, this object can be destroyed with
140 .Fn mchars_free .
141 .Pp
142 The function
143 .Fn mchars_spec2cp
144 looks up a
145 .Xr roff 7
146 special character
147 .Fa name
148 consisting of
149 .Fa sz
150 characters in the
151 .Fa table
152 and returns the corresponding Unicode codepoint.
153 If the
154 .Ar name
155 is not recognized, \-1 is returned.
156 For example, the
157 .Xr mandoc 1
158 .Fl Tutf8
159 and
160 .Fl Thtml
161 output modules use this function to render
162 .Xr roff 7
163 .Ic \e[ Ns Ar name Ns Ic \&]
164 and
165 .Ic \eC\(aq Ns Ar name Ns Ic \(aq
166 escape sequences.
167 .Pp
168 The function
169 .Fn mchars_spec2str
170 looks up a
171 .Xr roff 7
172 special character
173 .Fa name
174 consisting of
175 .Fa sz
176 characters in the
177 .Fa table
178 and returns an ASCII string representation.
179 The length of the representation is returned in
180 .Fa rsz .
181 In many cases, the meaning of such ASCII representations
182 is not quite obvious, so using
183 .Xr roff 7
184 special characters in documents intended for ASCII rendering
185 is usually a bad idea.
186 If the
187 .Ar name
188 is not recognized,
189 .Dv NULL
190 is returned.
191 For example,
192 .Xr makewhatis 8
193 and the
194 .Xr mandoc 1
195 .Fl Tascii
196 output module use this function to render
197 .Xr roff 7
198 .Ic \e[ Ns Ar name Ns Ic \&]
199 and
200 .Ic \eC\(aq Ns Ar name Ns Ic \(aq
201 escape sequences.
202 .Sh FILES
203 These funtions are implemented in the file
204 .Pa chars.c .
205 .Sh SEE ALSO
206 .Xr mandoc 1 ,
207 .Xr mandoc_escape 3 ,
208 .Xr mandoc_char 7 ,
209 .Xr roff 7
210 .Sh HISTORY
211 These functions and their predecessors have been available since the
212 following mandoc versions:
213 .Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10"
214 .It Sy function Ta since Ta Sy predecessor Ta since
215 .It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3
216 .It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0
217 .It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10
218 .It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em
219 .It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5
220 .It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3
221 .El
222 .Sh AUTHORS
223 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
224 .An Ingo Schwarze Aq Mt schwarze@openbsd.org