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