Provide strcasestr(3) and strsep(3) for Solaris 10 compat;

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 5fc05a859372a80211500d5d971b708f9dbb533c..fe6503d5477ef050ef9c371f4be86b7b0dc2b9d7 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.12 2011/07/11 08:43:27 kristaps Exp $
+.\"    $Id: mandoc.3,v 1.22 2013/10/06 17:01:52 schwarze 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,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.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: July 11 2011 $
+.Dd $Mdocdate: October 6 2013 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Nm mandoc_escape ,
 .Nm man_meta ,
 .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 ,
 .Nm man_node ,
 .Nm mchars_alloc ,
 .Nm mchars_free ,


@@ -33,6 +34,8 @@
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
 .Nm mparse_free ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
 .Nm mparse_free ,

+.Nm mparse_getkeep ,
+.Nm mparse_keep ,

 .Nm mparse_readfd ,
 .Nm mparse_reset ,
 .Nm mparse_result ,
 .Nm mparse_readfd ,
 .Nm mparse_reset ,
 .Nm mparse_result ,


@@ -40,27 +43,31 @@
 .Nm mparse_strlevel
 .Nd mandoc macro compiler library
 .Sh LIBRARY
 .Nm mparse_strlevel
 .Nd mandoc macro compiler library
 .Sh LIBRARY

-.Lb mandoc
+.Lb libmandoc

 .Sh SYNOPSIS
 .In man.h
 .In mdoc.h
 .In mandoc.h
 .Ft "enum mandoc_esc"
 .Fo mandoc_escape
 .Sh SYNOPSIS
 .In man.h
 .In mdoc.h
 .In mandoc.h
 .Ft "enum mandoc_esc"
 .Fo mandoc_escape

-.Fa "const char **in"
-.Fa "const char **seq"
-.Fa "int *len"
+.Fa "const char const **end"
+.Fa "const char const **start"
+.Fa "int *sz"

 .Fc
 .Ft "const struct man_meta *"
 .Fo man_meta
 .Fa "const struct man *man"
 .Fc
 .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"
 .Fc
 .Ft "struct mchars *"
 .Ft "const struct man_node *"
 .Fo man_node
 .Fa "const struct man *man"
 .Fc
 .Ft "struct mchars *"

-.Fn mchars_alloc
+.Fn mchars_alloc "void"

 .Ft void
 .Fn mchars_free "struct mchars *p"
 .Ft char
 .Ft void
 .Fn mchars_free "struct mchars *p"
 .Ft char


@@ -69,17 +76,16 @@
 .Fn mchars_num2uc "const char *cp" "size_t sz"
 .Ft "const char *"
 .Fo mchars_spec2str
 .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 "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"
 .Fa "const char *cp"
 .Fa "size_t sz"

-.Ft "const char *"

 .Fc
 .Ft "const struct mdoc_meta *"
 .Fo mdoc_meta
 .Fc
 .Ft "const struct mdoc_meta *"
 .Fo mdoc_meta


@@ -100,6 +106,14 @@
 .Fo mparse_free
 .Fa "struct mparse *parse"
 .Fc
 .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"
 .Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fa "struct mparse *parse"


@@ -219,7 +233,9 @@ messages emitted by the parser.
 .It Fn mandoc_escape
 Scan an escape sequence, i.e., a character string beginning with
 .Sq \e .
 .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
 .Va end ;
 it will be set to the supremum of the parsed escape sequence unless
 returning


@@ -240,14 +256,32 @@ and
 .Va sz
 may be
 .Dv NULL .
 .Va sz
 may be
 .Dv NULL .

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa mandoc.c .

 .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_meta
 Obtain the meta-data of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .

+Declared in
+.In man.h ,
+implemented in
+.Pa man.c .
+.It Fn man_mparse
+Get the parser used for the current output.
+Declared in
+.In man.h ,
+implemented in
+.Pa man.c .

 .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 man_node
 Obtain the root node of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .

+Declared in
+.In man.h ,
+implemented in
+.Pa man.c .

 .It Fn mchars_alloc
 Allocate an
 .Vt "struct mchars *"
 .It Fn mchars_alloc
 Allocate an
 .Vt "struct mchars *"


@@ -257,33 +291,65 @@ See
 for an overview of special characters.
 The object must be freed with
 .Fn mchars_free .
 for an overview of special characters.
 The object must be freed with
 .Fn mchars_free .

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

 .It Fn mchars_free
 Free an object created with
 .Fn mchars_alloc .
 .It Fn mchars_free
 Free an object created with
 .Fn mchars_alloc .

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

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

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

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

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

 .It Fn mchars_spec2cp
 Convert a special character into a valid Unicode codepoint.
 Returns \-1 on failure or a non-zero Unicode codepoint on success.
 .It Fn mchars_spec2cp
 Convert a special character into a valid Unicode codepoint.
 Returns \-1 on failure or a non-zero Unicode codepoint on success.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

 .It Fn mchars_spec2str
 Convert a special character into an ASCII string.
 Returns
 .Dv NULL
 on failure.
 .It Fn mchars_spec2str
 Convert a special character into an ASCII string.
 Returns
 .Dv NULL
 on failure.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .

 .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_meta
 Obtain the meta-data of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .

+Declared in
+.In mdoc.h ,
+implemented in
+.Pa mdoc.c .

 .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 mdoc_node
 Obtain the root node of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .

+Declared in
+.In mdoc.h ,
+implemented in
+.Pa mdoc.c .

 .It Fn mparse_alloc
 Allocate a parser.
 The same parser may be used for multiple files so long as
 .It Fn mparse_alloc
 Allocate a parser.
 The same parser may be used for multiple files so long as


@@ -291,9 +357,34 @@ The same parser may be used for multiple files so long as
 is called between parses.
 .Fn mparse_free
 must be called to free the memory allocated by this function.
 is called between parses.
 .Fn mparse_free
 must be called to free the memory allocated by this function.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .It Fn mparse_free
 Free all memory allocated by
 .Fn mparse_alloc .
 .It Fn mparse_free
 Free all memory allocated by
 .Fn mparse_alloc .

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
+.It Fn mparse_getkeep
+Acquire the keep buffer.
+Must follow a call of
+.Fn mparse_keep .
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
+.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.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .It Fn mparse_readfd
 Parse a file or file descriptor.
 If
 .It Fn mparse_readfd
 Parse a file or file descriptor.
 If


@@ -308,10 +399,18 @@ is assumed to be the name associated with
 This may be called multiple times with different parameters; however,
 .Fn mparse_reset
 should be invoked between parses.
 This may be called multiple times with different parameters; however,
 .Fn mparse_reset
 should be invoked between parses.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

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

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .It Fn mparse_result
 Obtain the result of a parse.
 Only successful parses
 .It Fn mparse_result
 Obtain the result of a parse.
 Only successful parses


@@ -322,10 +421,22 @@ returned less than MANDOCLEVEL_FATAL
 .Pc
 should invoke this function, in which case one of the two pointers will
 be filled in.
 .Pc
 should invoke this function, in which case one of the two pointers will
 be filled in.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .It Fn mparse_strerror
 Return a statically-allocated string representation of an error code.
 .It Fn mparse_strerror
 Return a statically-allocated string representation of an error code.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .It Fn mparse_strlevel
 Return a statically-allocated string representation of a level code.
 .It Fn mparse_strlevel
 Return a statically-allocated string representation of a level code.

+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .El
 .Ss Variables
 .Bl -ohang
 .El
 .Ss Variables
 .Bl -ohang


@@ -568,4 +679,4 @@ levels of badly-nested blocks.
 The
 .Nm
 library was written by
 The
 .Nm
 library was written by

-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .