Annotation of mandoc/mchars_alloc.3, Revision 1.2
1.2 ! schwarze 1: .\" $Id: mchars_alloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
1.1 schwarze 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: .\"
1.2 ! schwarze 17: .Dd $Mdocdate: August 5 2014 $
1.1 schwarze 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
1.2 ! schwarze 62: .Ft "const char *"
! 63: .Fn mchars_uc2str "int codepoint"
1.1 schwarze 64: .Sh DESCRIPTION
65: These functions translate Unicode character numbers and
66: .Xr roff 7
67: character names into glyphs.
68: See
69: .Xr mandoc_char 7
70: for a list of
71: .Xr roff 7
72: special characters.
73: These functions are intended for external use by programs formatting
74: .Xr mdoc 7
75: and
76: .Xr man 7
77: pages for output, for example the
78: .Xr mandoc 1
79: output formatter modules and
80: .Xr makewhatis 8 .
81: The
82: .Fa decimal ,
83: .Fa hexadecimal ,
84: .Fa name ,
85: and
86: .Fa size
87: input arguments are usually obtained from the
88: .Xr mandoc_escape 3
89: parser function.
90: .Pp
91: The function
92: .Fn mchars_num2char
93: converts a
94: .Fa decimal
95: string representation of a character number consisting of
96: .Fa sz
97: digits into a printable ASCII character.
98: If the input string is non-numeric or does not represent a printable
99: ASCII character, the NUL character
100: .Pq Sq \e0
101: is returned.
102: For example, the
103: .Xr mandoc 1
104: .Fl Tascii ,
105: .Fl Tutf8 ,
106: and
107: .Fl Thtml
108: output modules use this function to render
109: .Xr roff 7
110: .Ic \eN
111: escape sequences.
112: .Pp
113: The function
114: .Fn mchars_num2uc
115: converts a
116: .Fa hexadecimal
117: string representation of a Unicode codepoint consisting of
118: .Fa sz
119: digits into an integer representation.
120: If the input string is non-numeric or represents an ASCII character,
121: the NUL character
122: .Pq Sq \e0
123: is returned.
124: For example, the
125: .Xr mandoc 1
126: .Fl Tutf8
127: and
128: .Fl Thtml
129: output modules use this function to render
130: .Xr roff 7
131: .Ic \e[u Ns Ar XXXX Ns Ic \&]
132: and
133: .Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq
134: escape sequences.
135: .Pp
136: The function
137: .Fn mchars_alloc
138: allocates an opaque
139: .Vt "struct mchars *"
140: table object for subsequent use by the following two lookup functions.
141: When no longer needed, this object can be destroyed with
142: .Fn mchars_free .
143: .Pp
144: The function
145: .Fn mchars_spec2cp
146: looks up a
147: .Xr roff 7
148: special character
149: .Fa name
150: consisting of
151: .Fa sz
152: characters in the
153: .Fa table
154: and returns the corresponding Unicode codepoint.
155: If the
156: .Ar name
157: is not recognized, \-1 is returned.
158: For example, the
159: .Xr mandoc 1
160: .Fl Tutf8
161: and
162: .Fl Thtml
163: output modules use this function to render
164: .Xr roff 7
165: .Ic \e[ Ns Ar name Ns Ic \&]
166: and
167: .Ic \eC\(aq Ns Ar name Ns Ic \(aq
168: escape sequences.
169: .Pp
170: The function
171: .Fn mchars_spec2str
172: looks up a
173: .Xr roff 7
174: special character
175: .Fa name
176: consisting of
177: .Fa sz
178: characters in the
179: .Fa table
180: and returns an ASCII string representation.
181: The length of the representation is returned in
182: .Fa rsz .
183: In many cases, the meaning of such ASCII representations
184: is not quite obvious, so using
185: .Xr roff 7
186: special characters in documents intended for ASCII rendering
187: is usually a bad idea.
188: If the
189: .Ar name
190: is not recognized,
191: .Dv NULL
192: is returned.
193: For example,
194: .Xr makewhatis 8
195: and the
196: .Xr mandoc 1
197: .Fl Tascii
198: output module use this function to render
199: .Xr roff 7
200: .Ic \e[ Ns Ar name Ns Ic \&]
201: and
202: .Ic \eC\(aq Ns Ar name Ns Ic \(aq
203: escape sequences.
1.2 ! schwarze 204: .Pp
! 205: The function
! 206: .Fn mchars_uc2str
! 207: performs a reverse lookup of the Unicode
! 208: .Fa codepoint
! 209: and returns an ASCII string representation, or the string
! 210: .Qq <?>
! 211: if none is available.
1.1 schwarze 212: .Sh FILES
213: These funtions are implemented in the file
214: .Pa chars.c .
215: .Sh SEE ALSO
216: .Xr mandoc 1 ,
217: .Xr mandoc_escape 3 ,
218: .Xr mandoc_char 7 ,
219: .Xr roff 7
220: .Sh HISTORY
221: These functions and their predecessors have been available since the
222: following mandoc versions:
223: .Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10"
224: .It Sy function Ta since Ta Sy predecessor Ta since
225: .It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3
226: .It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0
227: .It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10
228: .It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em
229: .It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5
230: .It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3
1.2 ! schwarze 231: .It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em
1.1 schwarze 232: .El
233: .Sh AUTHORS
234: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
235: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
CVSweb