225 lines
5.1 KiB
Groff
225 lines
5.1 KiB
Groff
|
.\" $Id: mchars_alloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
|
||
|
.\"
|
||
|
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
|
||
|
.\"
|
||
|
.\" Permission to use, copy, modify, and distribute this software for any
|
||
|
.\" purpose with or without fee is hereby granted, provided that the above
|
||
|
.\" copyright notice and this permission notice appear in all copies.
|
||
|
.\"
|
||
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||
|
.\"
|
||
|
.Dd $Mdocdate: August 5 2014 $
|
||
|
.Dt MCHARS_ALLOC 3
|
||
|
.Os
|
||
|
.Sh NAME
|
||
|
.Nm mchars_alloc ,
|
||
|
.Nm mchars_free ,
|
||
|
.Nm mchars_num2char ,
|
||
|
.Nm mchars_num2uc ,
|
||
|
.Nm mchars_spec2cp ,
|
||
|
.Nm mchars_spec2str
|
||
|
.Nd character table for mandoc
|
||
|
.Sh LIBRARY
|
||
|
.Lb libmandoc
|
||
|
.Sh SYNOPSIS
|
||
|
.In sys/types.h
|
||
|
.In mandoc.h
|
||
|
.Ft "struct mchars *"
|
||
|
.Fn mchars_alloc "void"
|
||
|
.Ft void
|
||
|
.Fo mchars_free
|
||
|
.Fa "struct mchars *table"
|
||
|
.Fc
|
||
|
.Ft char
|
||
|
.Fo mchars_num2char
|
||
|
.Fa "const char *decimal"
|
||
|
.Fa "size_t sz"
|
||
|
.Fc
|
||
|
.Ft int
|
||
|
.Fo mchars_num2uc
|
||
|
.Fa "const char *hexadecimal"
|
||
|
.Fa "size_t sz"
|
||
|
.Fc
|
||
|
.Ft int
|
||
|
.Fo mchars_spec2cp
|
||
|
.Fa "const struct mchars *table"
|
||
|
.Fa "const char *name"
|
||
|
.Fa "size_t sz"
|
||
|
.Fc
|
||
|
.Ft "const char *"
|
||
|
.Fo mchars_spec2str
|
||
|
.Fa "const struct mchars *table"
|
||
|
.Fa "const char *name"
|
||
|
.Fa "size_t sz"
|
||
|
.Fa "size_t *rsz"
|
||
|
.Fc
|
||
|
.Sh DESCRIPTION
|
||
|
These functions translate Unicode character numbers and
|
||
|
.Xr roff 7
|
||
|
character names into glyphs.
|
||
|
See
|
||
|
.Xr mandoc_char 7
|
||
|
for a list of
|
||
|
.Xr roff 7
|
||
|
special characters.
|
||
|
These functions are intended for external use by programs formatting
|
||
|
.Xr mdoc 7
|
||
|
and
|
||
|
.Xr man 7
|
||
|
pages for output, for example the
|
||
|
.Xr mandoc 1
|
||
|
output formatter modules and
|
||
|
.Xr makewhatis 8 .
|
||
|
The
|
||
|
.Fa decimal ,
|
||
|
.Fa hexadecimal ,
|
||
|
.Fa name ,
|
||
|
and
|
||
|
.Fa size
|
||
|
input arguments are usually obtained from the
|
||
|
.Xr mandoc_escape 3
|
||
|
parser function.
|
||
|
.Pp
|
||
|
The function
|
||
|
.Fn mchars_num2char
|
||
|
converts a
|
||
|
.Fa decimal
|
||
|
string representation of a character number consisting of
|
||
|
.Fa sz
|
||
|
digits into a printable ASCII character.
|
||
|
If the input string is non-numeric or does not represent a printable
|
||
|
ASCII character, the NUL character
|
||
|
.Pq Sq \e0
|
||
|
is returned.
|
||
|
For example, the
|
||
|
.Xr mandoc 1
|
||
|
.Fl Tascii ,
|
||
|
.Fl Tutf8 ,
|
||
|
and
|
||
|
.Fl Thtml
|
||
|
output modules use this function to render
|
||
|
.Xr roff 7
|
||
|
.Ic \eN
|
||
|
escape sequences.
|
||
|
.Pp
|
||
|
The function
|
||
|
.Fn mchars_num2uc
|
||
|
converts a
|
||
|
.Fa hexadecimal
|
||
|
string representation of a Unicode codepoint consisting of
|
||
|
.Fa sz
|
||
|
digits into an integer representation.
|
||
|
If the input string is non-numeric or represents an ASCII character,
|
||
|
the NUL character
|
||
|
.Pq Sq \e0
|
||
|
is returned.
|
||
|
For example, the
|
||
|
.Xr mandoc 1
|
||
|
.Fl Tutf8
|
||
|
and
|
||
|
.Fl Thtml
|
||
|
output modules use this function to render
|
||
|
.Xr roff 7
|
||
|
.Ic \e[u Ns Ar XXXX Ns Ic \&]
|
||
|
and
|
||
|
.Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq
|
||
|
escape sequences.
|
||
|
.Pp
|
||
|
The function
|
||
|
.Fn mchars_alloc
|
||
|
allocates an opaque
|
||
|
.Vt "struct mchars *"
|
||
|
table object for subsequent use by the following two lookup functions.
|
||
|
When no longer needed, this object can be destroyed with
|
||
|
.Fn mchars_free .
|
||
|
.Pp
|
||
|
The function
|
||
|
.Fn mchars_spec2cp
|
||
|
looks up a
|
||
|
.Xr roff 7
|
||
|
special character
|
||
|
.Fa name
|
||
|
consisting of
|
||
|
.Fa sz
|
||
|
characters in the
|
||
|
.Fa table
|
||
|
and returns the corresponding Unicode codepoint.
|
||
|
If the
|
||
|
.Ar name
|
||
|
is not recognized, \-1 is returned.
|
||
|
For example, the
|
||
|
.Xr mandoc 1
|
||
|
.Fl Tutf8
|
||
|
and
|
||
|
.Fl Thtml
|
||
|
output modules use this function to render
|
||
|
.Xr roff 7
|
||
|
.Ic \e[ Ns Ar name Ns Ic \&]
|
||
|
and
|
||
|
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
|
||
|
escape sequences.
|
||
|
.Pp
|
||
|
The function
|
||
|
.Fn mchars_spec2str
|
||
|
looks up a
|
||
|
.Xr roff 7
|
||
|
special character
|
||
|
.Fa name
|
||
|
consisting of
|
||
|
.Fa sz
|
||
|
characters in the
|
||
|
.Fa table
|
||
|
and returns an ASCII string representation.
|
||
|
The length of the representation is returned in
|
||
|
.Fa rsz .
|
||
|
In many cases, the meaning of such ASCII representations
|
||
|
is not quite obvious, so using
|
||
|
.Xr roff 7
|
||
|
special characters in documents intended for ASCII rendering
|
||
|
is usually a bad idea.
|
||
|
If the
|
||
|
.Ar name
|
||
|
is not recognized,
|
||
|
.Dv NULL
|
||
|
is returned.
|
||
|
For example,
|
||
|
.Xr makewhatis 8
|
||
|
and the
|
||
|
.Xr mandoc 1
|
||
|
.Fl Tascii
|
||
|
output module use this function to render
|
||
|
.Xr roff 7
|
||
|
.Ic \e[ Ns Ar name Ns Ic \&]
|
||
|
and
|
||
|
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
|
||
|
escape sequences.
|
||
|
.Sh FILES
|
||
|
These funtions are implemented in the file
|
||
|
.Pa chars.c .
|
||
|
.Sh SEE ALSO
|
||
|
.Xr mandoc 1 ,
|
||
|
.Xr mandoc_escape 3 ,
|
||
|
.Xr mandoc_char 7 ,
|
||
|
.Xr roff 7
|
||
|
.Sh HISTORY
|
||
|
These functions and their predecessors have been available since the
|
||
|
following mandoc versions:
|
||
|
.Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10"
|
||
|
.It Sy function Ta since Ta Sy predecessor Ta since
|
||
|
.It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3
|
||
|
.It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0
|
||
|
.It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10
|
||
|
.It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em
|
||
|
.It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5
|
||
|
.It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3
|
||
|
.El
|
||
|
.Sh AUTHORS
|
||
|
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
|
||
|
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
|