Annotation of mandoc/mchars_alloc.3, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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$
! 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
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mchars_alloc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc