[BACK]Return to mchars_alloc.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mchars_alloc.3, Revision 1.2

1.2     ! schwarze    1: .\"    $Id: mchars_alloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
1.1       schwarze    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: .\"
1.2     ! schwarze   17: .Dd $Mdocdate: August 5 2014 $
1.1       schwarze   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
1.2     ! schwarze   62: .Ft "const char *"
        !            63: .Fn mchars_uc2str "int codepoint"
1.1       schwarze   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.
1.2     ! schwarze  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.
1.1       schwarze  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
1.2     ! schwarze  231: .It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em
1.1       schwarze  232: .El
                    233: .Sh AUTHORS
                    234: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    235: .An Ingo Schwarze Aq Mt schwarze@openbsd.org

CVSweb