contrib/mdocml/mchars_alloc.3

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