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 ec765c6bd9c7f3b3572fda003efdd840ebc4d6e2..313b35374ffa67c52ad2c29a2fce2677567ad40d 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.3 2011/04/09 15:53:48 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 9 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"


@@ -97,6 +127,8 @@
 .Vt extern const char * const * man_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * man_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;

+.Fd "#define ASCII_NBRSP"
+.Fd "#define ASCII_HYPH"

 .Sh DESCRIPTION
 The
 .Nm mandoc
 .Sh DESCRIPTION
 The
 .Nm mandoc


@@ -138,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


@@ -147,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"


@@ -154,23 +201,121 @@ via
 .Ss Functions
 .Bl -ohang
 .It Fn mandoc_escape
 .Ss Functions
 .Bl -ohang
 .It Fn mandoc_escape

+Scan an escape sequence, i.e., a character string beginning with
+.Sq \e .
+Pass a pointer to this string as
+.Va end ;
+it will be set to the supremum of the parsed escape sequence unless
+returning ESCAPE_ERROR, in which case the string is bogus and should be
+thrown away.
+If not ESCAPE_ERROR or ESCAPE_IGNORE,
+.Va start
+is set to the first relevant character of the substring (font, glyph,
+whatever) of length
+.Va sz .
+Both
+.Va start
+and
+.Va sz
+may be NULL.

 .It Fn man_meta
 .It Fn man_meta

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

 .It Fn man_node
 .It Fn man_node

+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
 .It Fn mdoc_meta

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

 .It Fn mdoc_node
 .It Fn mdoc_node

+Obtain the root node of a successful parse.
+This may only be used on a pointer returned by
+.Fn mparse_result .

 .It Fn mparse_alloc
 .It Fn mparse_alloc

+Allocate a parser.
+The same parser may be used for multiple files so long as
+.Fn mparse_reset
+is called between parses.
+.Fn mparse_free
+must be called to free the memory allocated by this function.

 .It Fn mparse_free
 .It Fn mparse_free

+Free all memory allocated by
+.Fn mparse_alloc .

 .It Fn mparse_readfd
 .It Fn mparse_readfd

+Parse a file or file descriptor.
+If
+.Va fd
+is -1,
+.Va fname
+is opened for reading.
+Otherwise,
+.Va fname
+is assumed to be the name associated with
+.Va fd .
+This may be called multiple times with different parameters; however,
+.Fn mparse_reset
+should be invoked between parses.

 .It Fn mparse_reset
 .It Fn mparse_reset

+Reset a parser so that
+.Fn mparse_readfd
+may be used again.

 .It Fn mparse_result
 .It Fn mparse_result

+Obtain the result of a parse.
+Only successful parses
+.Po
+i.e., those where
+.Fn mparse_readfd
+returned less than MANDOCLEVEL_FATAL
+.Pc
+should invoke this function, in which case one of the two pointers will
+be filled in.

 .It Fn mparse_strerror
 .It Fn mparse_strerror

+Return a statically-allocated string representation of an error code.

 .It Fn mparse_strlevel
 .It Fn mparse_strlevel

+Return a statically-allocated string representation of a level code.

 .El
 .Ss Variables
 .Bl -ohang
 .It Va man_macronames
 .El
 .Ss Variables
 .Bl -ohang
 .It Va man_macronames

+The string representation of a man macro as indexed by
+.Vt "enum mant" .

 .It Va mdoc_argnames
 .It Va mdoc_argnames

+The string representation of a mdoc macro argument as indexed by
+.Vt "enum mdocargt" .

 .It Va mdoc_macronames
 .It Va mdoc_macronames

+The string representation of a mdoc macro as indexed by
+.Vt "enum mdoct" .

 .El
 .Sh IMPLEMENTATION NOTES
 This section consists of structural documentation for
 .El
 .Sh IMPLEMENTATION NOTES
 This section consists of structural documentation for


@@ -292,7 +437,7 @@ where a new body introduces a new phrase.
 .Pp
 The
 .Xr mdoc 7
 .Pp
 The
 .Xr mdoc 7

-syntax tree accomodates for broken block structures as well.
+syntax tree accommodates for broken block structures as well.

 The ENDBODY node is available to end the formatting associated
 with a given block before the physical end of that block.
 It has a non-null
 The ENDBODY node is available to end the formatting associated
 with a given block before the physical end of that block.
 It has a non-null


@@ -364,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