contrib/mandoc/mchars_alloc.3

   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
  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
 133 initializes a static
 134 .Vt "struct ohash"
 135 object for subsequent use by the following two lookup functions.
 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
 147 characters and returns the corresponding Unicode codepoint.
 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
 171 characters and returns an ASCII string representation.
 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.
 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.
 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 ,
 209 .Xr ohash_init 3 ,
 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
 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