contrib/mdocml/mchars_alloc.3

   1 .\"     $Id: mchars_alloc.3,v 1.3 2015/10/13 22:59:54 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: October 13 2015 $
  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
  32 .Fn mchars_alloc void
  33 .Ft void
  34 .Fn mchars_free void
  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
  56 .Ft "const char *"
  57 .Fn mchars_uc2str "int codepoint"
  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
 132 initializes a static
 133 .Vt "struct ohash"
 134 object for subsequent use by the following two lookup functions.
 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
 146 characters and returns the corresponding Unicode codepoint.
 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
 170 characters and returns an ASCII string representation.
 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.
 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.
 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 ,
 208 .Xr ohash_init 3 ,
 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
 222 .It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em
 223 .El
 224 .Sh AUTHORS
 225 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 226 .An Ingo Schwarze Aq Mt schwarze@openbsd.org