Remove all references to ESCAPE_PREDEF, which is now not exposed passed

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 0262da6020e5bf30e8675033c2cd3962a5f6597d..313b35374ffa67c52ad2c29a2fce2677567ad40d 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.5 2011/04/30 10:18:24 kristaps Exp $
+.\"    $Id: mandoc.3,v 1.9 2011/05/24 21:31:23 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: April 30 2011 $
+.Dd $Mdocdate: May 24 2011 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Dt MANDOC 3
 .Os
 .Sh NAME


@@ -23,6 +23,12 @@
 .Nm mandoc_escape ,
 .Nm man_meta ,
 .Nm man_node ,
 .Nm mandoc_escape ,
 .Nm man_meta ,
 .Nm man_node ,

+.Nm mchars_alloc ,
+.Nm mchars_free ,
+.Nm mchars_num2char ,
+.Nm mchars_num2uc ,
+.Nm mchars_spec2cp ,
+.Nm mchars_spec2str ,

 .Nm mdoc_meta ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
 .Nm mdoc_meta ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,


@@ -33,6 +39,8 @@
 .Nm mparse_strerror ,
 .Nm mparse_strlevel
 .Nd mandoc macro compiler library
 .Nm mparse_strerror ,
 .Nm mparse_strlevel
 .Nd mandoc macro compiler library

+.Sh LIBRARY
+.Lb mandoc

 .Sh SYNOPSIS
 .In man.h
 .In mdoc.h
 .Sh SYNOPSIS
 .In man.h
 .In mdoc.h


@@ -51,6 +59,28 @@
 .Fo man_node
 .Fa "const struct man *man"
 .Fc
 .Fo man_node
 .Fa "const struct man *man"
 .Fc

+.Ft "struct mchars *"
+.Fn mchars_alloc
+.Ft void
+.Fn mchars_free "struct mchars *p"
+.Ft char
+.Fn mchars_num2char "const char *cp" "size_t sz"
+.Ft int
+.Fn mchars_num2uc "const char *cp" "size_t sz"
+.Ft "const char *"
+.Fo mchars_spec2str
+.Fa "struct mchars *p"
+.Fa "const char *cp"
+.Fa "size_t sz"
+.Fa "size_t *rsz"
+.Fc
+.Ft int
+.Fo mchars_spec2cp
+.Fa "struct mchars *p"
+.Fa "const char *cp"
+.Fa "size_t sz"
+.Ft "const char *"
+.Fc

 .Ft "const struct mdoc_meta *"
 .Fo mdoc_meta
 .Fa "const struct mdoc *mdoc"
 .Ft "const struct mdoc_meta *"
 .Fo mdoc_meta
 .Fa "const struct mdoc *mdoc"


@@ -140,6 +170,16 @@ or invoke
 .Fn mparse_reset
 and parse new files.
 .El
 .Fn mparse_reset
 and parse new files.
 .El

+.Pp
+The
+.Nm
+library also contains routines for translating character strings into glyphs
+.Pq see Fn mchars_alloc
+and parsing escape sequences from strings
+.Pq see Fn mandoc_escape .
+.Pp
+This library is
+.Ud

 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via
 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via


@@ -149,6 +189,11 @@ via
 .It Vt "enum mandoc_esc"
 .It Vt "enum mandocerr"
 .It Vt "enum mandoclevel"
 .It Vt "enum mandoc_esc"
 .It Vt "enum mandocerr"
 .It Vt "enum mandoclevel"

+.It Vt "struct mchars"
+An opaque pointer to an object allowing for translation between
+character strings and glyphs.
+See
+.Fn mchars_alloc .

 .It Vt "enum mparset"
 .It Vt "struct mparse"
 .It Vt "mandocmsg"
 .It Vt "enum mparset"
 .It Vt "struct mparse"
 .It Vt "mandocmsg"


@@ -181,6 +226,34 @@ This may only be used on a pointer returned by
 Obtain the root node of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Obtain the root node of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .

+.It Fn mchars_alloc
+Allocate an
+.Vt "struct mchars *"
+object for translating special characters into glyphs.
+See
+.Xr mandoc_char 7
+for an overview of special characters.
+The object must be freed with
+.Fn mchars_free .
+.It Fn mchars_free
+Free an object created with
+.Fn mchars_alloc .
+.It Fn mchars_num2char
+Convert a character index (e.g., the \eN\(aq\(aq escape) into a
+printable ASCII character.
+Returns \e0 (the nil character) if the input sequence is malformed.
+.It Fn mchars_num2uc
+Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
+a Unicode codepoint.
+Returns \e0 (the nil character) if the input sequence is malformed.
+.It Fn mchars_spec2cp
+Convert a special character into a valid Unicode codepoint.
+Returns \-1 on failure and 0 if no code-point exists (if this occurs,
+the caller should fall back to
+.Fn mchars_spec2str ) .
+.It Fn mchars_spec2str
+Convert a special character into an ASCII string.
+Returns NULL on failure.

 .It Fn mdoc_meta
 Obtain the meta-data of a successful parse.
 This may only be used on a pointer returned by
 .It Fn mdoc_meta
 Obtain the meta-data of a successful parse.
 This may only be used on a pointer returned by


@@ -436,6 +509,7 @@ levels of badly-nested blocks.
 .Xr mandoc 1 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc 1 ,
 .Xr eqn 7 ,
 .Xr man 7 ,

+.Xr mandoc_char 7 ,

 .Xr mdoc 7 ,
 .Xr roff 7 ,
 .Xr tbl 7
 .Xr mdoc 7 ,
 .Xr roff 7 ,
 .Xr tbl 7