.Dd $Mdocdate: October 13 2015 $

.Os

.Nm mchars_alloc ,

.Nm mchars_free ,

.Nm mchars_num2char ,

.Nm mchars_num2uc ,

.Nm mchars_spec2cp ,

.Nm mchars_spec2str

.Nd character table for mandoc

.In sys/types.h

.In mandoc.h

.Ft void

.Fn mchars_alloc void

.Ft void

.Fn mchars_free void

.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 char *name"

.Fa "size_t sz"

.Fc

.Ft "const char *"

.Fo mchars_spec2str

.Fa "const char *name"

.Fa "size_t sz"

.Fa "size_t *rsz"

.Fc

.Ft "const char *"

.Fn mchars_uc2str "int codepoint"

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

initializes a static

.Vt "struct ohash"

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 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 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.

.Pp

The function

.Fn mchars_uc2str

performs a reverse lookup of the Unicode

.Fa codepoint

and returns an ASCII string representation, or the string

.Qq <?>

if none is available.

These funtions are implemented in the file

.Pa chars.c .

.Xr mandoc 1 ,

.Xr mandoc_escape 3 ,

.Xr ohash_init 3 ,

.Xr mandoc_char 7 ,

.Xr roff 7

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

.It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em

.El

.An Kristaps Dzonsons Aq Mt [email protected]

.An Ingo Schwarze Aq Mt [email protected]