Small tweaks for release.

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 16aa612585aaae7c0b03fe4cc8e6aacb2ecb158b..4d0b20d6507e6e02f64e945c18fd5910a46dbb97 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.11 2011/06/22 22:10:02 kristaps Exp $
+.\"    $Id: mandoc.3,v 1.17 2012/01/13 15:27:14 joerg Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,13 +15,14 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 22 2011 $
+.Dd $Mdocdate: January 13 2012 $
 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Nm mandoc_escape ,
 .Nm man_meta ,
+.Nm man_mparse ,
 .Nm man_node ,
 .Nm mchars_alloc ,
 .Nm mchars_free ,
@@ -33,6 +34,8 @@
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
 .Nm mparse_free ,
+.Nm mparse_getkeep ,
+.Nm mparse_keep ,
 .Nm mparse_readfd ,
 .Nm mparse_reset ,
 .Nm mparse_result ,
@@ -47,14 +50,18 @@
 .In mandoc.h
 .Ft "enum mandoc_esc"
 .Fo mandoc_escape
-.Fa "const char **in"
-.Fa "const char **seq"
-.Fa "int *len"
+.Fa "const char **end"
+.Fa "const char **start"
+.Fa "int *sz"
 .Fc
 .Ft "const struct man_meta *"
 .Fo man_meta
 .Fa "const struct man *man"
 .Fc
+.Ft "const struct mparse *"
+.Fo man_mparse
+.Fa "const struct man *man"
+.Fc
 .Ft "const struct man_node *"
 .Fo man_node
 .Fa "const struct man *man"
@@ -69,14 +76,14 @@
 .Fn mchars_num2uc "const char *cp" "size_t sz"
 .Ft "const char *"
 .Fo mchars_spec2str
-.Fa "struct mchars *p"
+.Fa "const 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 struct mchars *p"
 .Fa "const char *cp"
 .Fa "size_t sz"
 .Ft "const char *"
@@ -100,6 +107,14 @@
 .Fo mparse_free
 .Fa "struct mparse *parse"
 .Fc
+.Ft void
+.Fo mparse_getkeep
+.Fa "const struct mparse *parse"
+.Fc
+.Ft void
+.Fo mparse_keep
+.Fa "struct mparse *parse"
+.Fc
 .Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fa "struct mparse *parse"
@@ -199,7 +214,7 @@ See
 .It Vt "enum mparset"
 The type of parser when reading input.
 This should usually be
-.Va MPARSE_AUTO
+.Dv MPARSE_AUTO
 for auto-detection.
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
@@ -219,12 +234,19 @@ messages emitted by the parser.
 .It Fn mandoc_escape
 Scan an escape sequence, i.e., a character string beginning with
 .Sq \e .
-Pass a pointer to this string as
+Pass a pointer to the character after the
+.Sq \e
+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
+returning
+.Dv ESCAPE_ERROR ,
+in which case the string is bogus and should be
 thrown away.
-If not ESCAPE_ERROR or ESCAPE_IGNORE,
+If not
+.Dv ESCAPE_ERROR
+or
+.Dv ESCAPE_IGNORE ,
 .Va start
 is set to the first relevant character of the substring (font, glyph,
 whatever) of length
@@ -233,11 +255,14 @@ Both
 .Va start
 and
 .Va sz
-may be NULL.
+may be
+.Dv NULL .
 .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_mparse
+Get the parser used for the current output.
 .It Fn man_node
 Obtain the root node of a successful parse.
 This may only be used on a pointer returned by
@@ -267,7 +292,9 @@ Convert a special character into a valid Unicode codepoint.
 Returns \-1 on failure or a non-zero Unicode codepoint on success.
 .It Fn mchars_spec2str
 Convert a special character into an ASCII string.
-Returns NULL on failure.
+Returns
+.Dv 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
@@ -286,6 +313,15 @@ must be called to free the memory allocated by this function.
 .It Fn mparse_free
 Free all memory allocated by
 .Fn mparse_alloc .
+.It Fn mparse_getkeep
+Acquire the keep buffer.
+Must follow a call of
+.Fn mparse_keep .
+.It Fn mparse_keep
+Instruct the parser to retain a copy of its parsed input.
+This can be acquired with subsequent
+.Fn mparse_getkeep
+calls.
 .It Fn mparse_readfd
 Parse a file or file descriptor.
 If
@@ -560,4 +596,5 @@ levels of badly-nested blocks.
 The
 .Nm
 library was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .