=================================================================== RCS file: /cvs/mandoc/mandoc.3,v retrieving revision 1.17 retrieving revision 1.23 diff -u -p -r1.17 -r1.23 --- mandoc/mandoc.3 2012/01/13 15:27:14 1.17 +++ mandoc/mandoc.3 2014/01/05 20:26:36 1.23 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.3,v 1.17 2012/01/13 15:27:14 joerg Exp $ +.\" $Id: mandoc.3,v 1.23 2014/01/05 20:26:36 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze @@ -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. .\" -.Dd $Mdocdate: January 13 2012 $ +.Dd $Mdocdate: January 5 2014 $ .Dt MANDOC 3 .Os .Sh NAME @@ -43,7 +43,7 @@ .Nm mparse_strlevel .Nd mandoc macro compiler library .Sh LIBRARY -.Lb mandoc +.Lb libmandoc .Sh SYNOPSIS .In man.h .In mdoc.h @@ -67,7 +67,7 @@ .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 @@ -86,7 +86,6 @@ .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 @@ -98,16 +97,17 @@ .Fc .Ft void .Fo mparse_alloc -.Fa "enum mparset type" +.Fa "enum mparset inttype" .Fa "enum mandoclevel wlevel" -.Fa "mandocmsg msg" -.Fa "void *msgarg" +.Fa "mandocmsg mmsg" +.Fa "char *defos" +.Fa "int quick" .Fc .Ft void .Fo mparse_free .Fa "struct mparse *parse" .Fc -.Ft void +.Ft const char * .Fo mparse_getkeep .Fa "const struct mparse *parse" .Fc @@ -204,7 +204,7 @@ An escape sequence classification. A fatal error, error, or warning message during parsing. .It Vt "enum mandoclevel" A classification of an -.Vt "enum mandoclevel" +.Vt "enum mandocerr" as regards system operation. .It Vt "struct mchars" An opaque pointer to an object allowing for translation between @@ -257,16 +257,32 @@ and .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 . +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 *" @@ -276,52 +292,136 @@ 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 .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 arguments have the following effect: +.Bl -tag -offset 5n -width inttype +.It Ar inttype +When set to +.Dv MPARSE_MDOC +or +.Dv MPARSE_MAN , +only that parser will be used. +With +.Dv MPARSE_AUTO , +the document type will be automatically detected. +.It Ar wlevel +Can be set to +.Dv MANDOCLEVEL_FATAL , +.Dv MANDOCLEVEL_ERROR , +or +.Dv MANDOCLEVEL_WARNING . +Messages below the selected level will be suppressed. +.It Ar mmsg +A callback function to handle errors and warnings. +See +.Pa main.c +for an example. +.It Ar defos +A default string for the +.Xr mdoc 7 +.Sq \&Os +macro, overriding the +.Dv OSNAME +preprocessor definition and the results of +.Xr uname 3 . +.It Ar quick +When set, parsing is aborted after the NAME section. +This is for example useful to quickly build minimal databases. +.El +.Pp 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. +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 @@ -336,10 +436,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 @@ -350,10 +458,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 @@ -596,5 +716,4 @@ levels of badly-nested blocks. The .Nm library was written by -.An Kristaps Dzonsons , -.Mt kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .