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