=================================================================== RCS file: /cvs/mandoc/mandoc.3,v retrieving revision 1.11 retrieving revision 1.20 diff -u -p -r1.11 -r1.20 --- mandoc/mandoc.3 2011/06/22 22:10:02 1.11 +++ mandoc/mandoc.3 2013/09/16 22:54:38 1.20 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.3,v 1.11 2011/06/22 22:10:02 kristaps Exp $ +.\" $Id: mandoc.3,v 1.20 2013/09/16 22:54:38 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze @@ -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: September 16 2013 $ .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,20 +50,24 @@ .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" .Fc .Ft "struct mchars *" -.Fn mchars_alloc +.Fn mchars_alloc "void" .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 -.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 *" .Fc .Ft "const struct mdoc_meta *" .Fo mdoc_meta @@ -100,6 +106,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 +213,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 +233,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,15 +254,34 @@ Both .Va start and .Va sz -may be NULL. +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 . +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 . +Declared in +.In man.h , +implemented in +.Pa man.c . .It Fn mchars_alloc Allocate an .Vt "struct mchars *" @@ -251,31 +291,65 @@ See 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 . +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. +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. +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. +Declared in +.In mandoc.h , +implemented in +.Pa chars.c . .It Fn mchars_spec2str Convert a special character into an ASCII string. -Returns NULL on failure. +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 . +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 . +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 @@ -283,9 +357,34 @@ The same parser may be used for multiple files so long 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 . +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 @@ -300,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. +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. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . .It Fn mparse_result Obtain the result of a parse. Only successful parses @@ -314,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. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . .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. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . .El .Ss Variables .Bl -ohang @@ -560,4 +679,4 @@ levels of badly-nested blocks. The .Nm library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .