GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MCHARS_ALLOC (3)

NAME

mchars_alloc, mchars_free, mchars_num2char, mchars_num2uc, mchars_spec2cp, mchars_spec2str - character table for mandoc

CONTENTS

Library
Synopsis
Description
Files
See Also
History
Authors

LIBRARY


.Lb libmandoc

SYNOPSIS


.In sys/types.h
.In mandoc.h struct mchars * mchars_alloc void void
.Fo mchars_free struct mchars *table
.Fc char
.Fo mchars_num2char const char *decimal size_t sz
.Fc int
.Fo mchars_num2uc const char *hexadecimal size_t sz
.Fc int
.Fo mchars_spec2cp const struct mchars *table const char *name size_t sz
.Fc const char *
.Fo mchars_spec2str const struct mchars *table const char *name size_t sz size_t *rsz
.Fc const char * mchars_uc2str int codepoint

DESCRIPTION

These functions translate Unicode character numbers and roff(7) character names into glyphs. See mandoc_char(7) for a list of roff(7) special characters. These functions are intended for external use by programs formatting mdoc(7) and man(7) pages for output, for example the mandoc(1) output formatter modules and makewhatis(8). The decimal, hexadecimal, name, and size input arguments are usually obtained from the mandoc_escape(3) parser function.

The function mchars_num2char converts a decimal string representation of a character number consisting of 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 ('\0') is returned. For example, the mandoc(1) -Tascii , -Tutf8 , and -Thtml output modules use this function to render roff(7) \N escape sequences.

The function mchars_num2uc converts a hexadecimal string representation of a Unicode codepoint consisting of sz digits into an integer representation. If the input string is non-numeric or represents an ASCII character, the NUL character ('\0') is returned. For example, the mandoc(1) -Tutf8 and -Thtml output modules use this function to render roff(7) \[u XXXX ] and \C\(aqu XXXX \(aq escape sequences.

The function 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 mchars_free.

The function mchars_spec2cp looks up a roff(7) special character name consisting of sz characters in the table and returns the corresponding Unicode codepoint. If the name is not recognized, -1 is returned. For example, the mandoc(1) -Tutf8 and -Thtml output modules use this function to render roff(7) \[ name ] and \C\(aq name \(aq escape sequences.

The function mchars_spec2str looks up a roff(7) special character name consisting of sz characters in the table and returns an ASCII string representation. The length of the representation is returned in rsz. In many cases, the meaning of such ASCII representations is not quite obvious, so using roff(7) special characters in documents intended for ASCII rendering is usually a bad idea. If the name is not recognized, NULL is returned. For example, makewhatis(8) and the mandoc(1) -Tascii output module use this function to render roff(7) \[ name ] and \C\(aq name \(aq escape sequences.

The function mchars_uc2str performs a reverse lookup of the Unicode codepoint and returns an ASCII string representation, or the string "<?>" if none is available.

FILES

These funtions are implemented in the file chars.c.

SEE ALSO

mandoc(1), mandoc_escape(3), mandoc_char(7), roff(7)

HISTORY

These functions and their predecessors have been available since the following mandoc versions:
function      since      predecessor      since
mchars_alloc      1.11.3      ascii2htab      1.5.3
mchars_free      1.11.2      asciifree      1.6.0
mchars_num2char      1.11.2      chars_num2char      1.10.10
mchars_num2uc      1.11.3      —      —
mchars_spec2cp      1.11.2      chars_spec2cp      1.10.5
mchars_spec2str      1.11.2      a2ascii      1.5.3
mchars_uc2str      1.13.2      —      —
 

AUTHORS


.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.