contrib/mdocml/mchars_alloc.3

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