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