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