=================================================================== RCS file: /cvs/mandoc/mandoc.3,v retrieving revision 1.34 retrieving revision 1.43 diff -u -p -r1.34 -r1.43 --- mandoc/mandoc.3 2016/01/08 02:13:39 1.34 +++ mandoc/mandoc.3 2018/12/14 01:18:25 1.43 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.3,v 1.34 2016/01/08 02:13:39 schwarze Exp $ +.\" $Id: mandoc.3,v 1.43 2018/12/14 01:18:25 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2010, 2013, 2014, 2015 Ingo Schwarze +.\" Copyright (c) 2010-2017 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,31 +15,25 @@ .\" 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 8 2016 $ +.Dd $Mdocdate: December 14 2018 $ .Dt MANDOC 3 .Os .Sh NAME .Nm mandoc , -.Nm man_deroff , -.Nm man_meta , -.Nm man_mparse , -.Nm man_node , -.Nm mdoc_deroff , -.Nm mdoc_meta , -.Nm mdoc_node , +.Nm deroff , +.Nm man_validate , +.Nm mdoc_validate , .Nm mparse_alloc , +.Nm mparse_copy , .Nm mparse_free , -.Nm mparse_getkeep , -.Nm mparse_keep , .Nm mparse_open , .Nm mparse_readfd , .Nm mparse_reset , -.Nm mparse_result , -.Nm mparse_strerror , -.Nm mparse_strlevel +.Nm mparse_result .Nd mandoc macro compiler library .Sh SYNOPSIS .In sys/types.h +.In stdio.h .In mandoc.h .Pp .Fd "#define ASCII_NBRSP" @@ -48,38 +42,23 @@ .Ft struct mparse * .Fo mparse_alloc .Fa "int options" -.Fa "enum mandoclevel wlevel" -.Fa "mandocmsg mmsg" -.Fa "char *defos" +.Fa "enum mandoc_os oe_e" +.Fa "char *os_s" .Fc .Ft void -.Fo (*mandocmsg) -.Fa "enum mandocerr errtype" -.Fa "enum mandoclevel level" -.Fa "const char *file" -.Fa "int line" -.Fa "int col" -.Fa "const char *msg" -.Fc -.Ft void .Fo mparse_free .Fa "struct mparse *parse" .Fc -.Ft const char * -.Fo mparse_getkeep +.Ft void +.Fo mparse_copy .Fa "const struct mparse *parse" .Fc -.Ft void -.Fo mparse_keep -.Fa "struct mparse *parse" -.Fc -.Ft "enum mandoclevel" +.Ft int .Fo mparse_open .Fa "struct mparse *parse" -.Fa "int *fd" .Fa "const char *fname" .Fc -.Ft "enum mandoclevel" +.Ft void .Fo mparse_readfd .Fa "struct mparse *parse" .Fa "int fd" @@ -92,57 +71,32 @@ .Ft void .Fo mparse_result .Fa "struct mparse *parse" -.Fa "struct mdoc **mdoc" -.Fa "struct man **man" +.Fa "struct roff_man **man" .Fa "char **sodest" .Fc -.Ft "const char *" -.Fo mparse_strerror -.Fa "enum mandocerr" +.In roff.h +.Ft void +.Fo deroff +.Fa "char **dest" +.Fa "const struct roff_node *node" .Fc -.Ft "const char *" -.Fo mparse_strlevel -.Fa "enum mandoclevel" -.Fc .In sys/types.h .In mandoc.h .In mdoc.h -.Ft void -.Fo mdoc_deroff -.Fa "char **dest" -.Fa "const struct mdoc_node *node" -.Fc -.Ft "const struct mdoc_meta *" -.Fo mdoc_meta -.Fa "const struct mdoc *mdoc" -.Fc -.Ft "const struct mdoc_node *" -.Fo mdoc_node -.Fa "const struct mdoc *mdoc" -.Fc .Vt extern const char * const * mdoc_argnames; .Vt extern const char * const * mdoc_macronames; +.Ft void +.Fo mdoc_validate +.Fa "struct roff_man *mdoc" +.Fc .In sys/types.h .In mandoc.h .In man.h +.Vt extern const char * const * man_macronames; .Ft void -.Fo man_deroff -.Fa "char **dest" -.Fa "const struct man_node *node" +.Fo man_validate +.Fa "struct roff_man *man" .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 -.Vt extern const char * const * man_macronames; .Sh DESCRIPTION The .Nm mandoc @@ -183,18 +137,35 @@ close it with retrieve the syntax tree with .Fn mparse_result ; .It -iterate over parse nodes with -.Fn mdoc_node +depending on whether the +.Fa macroset +member of the returned +.Vt struct roff_man +is +.Dv MACROSET_MDOC or -.Fn man_node ; +.Dv MACROSET_MAN , +validate it with +.Fn mdoc_validate +or +.Fn man_validate , +respectively; .It +if information about the validity of the input is needed, fetch it with +.Fn mparse_updaterc ; +.It +iterate over parse nodes with starting from the +.Fa first +member of the returned +.Vt struct roff_man ; +.It free all allocated memory with .Fn mparse_free and .Xr mchars_free 3 , or invoke .Fn mparse_reset -and parse new files. +and go back to step 2 to parse new files. .El .Sh REFERENCE This section documents the functions, types, and variables available @@ -212,6 +183,9 @@ An error or warning message during parsing. A classification of an .Vt "enum mandocerr" as regards system operation. +See the DIAGNOSTICS section in +.Xr mandoc 1 +regarding the meanings of the levels. .It Vt "struct mparse" An opaque pointer to a running parse sequence. Created with @@ -221,78 +195,39 @@ and freed with This may be used across parsed input if .Fn mparse_reset is called between parses. -.It Vt "mandocmsg" -A prototype for a function to handle error and warning -messages emitted by the parser. .El .Ss Functions .Bl -ohang -.It Fn man_deroff +.It Fn deroff Obtain a text-only representation of a -.Vt struct man_node , +.Vt struct roff_node , including text contained in its child nodes. -To be used on children of the pointer returned from -.Fn man_node . +To be used on children of the +.Fa first +member of +.Vt struct roff_man . When it is no longer needed, the pointer returned from -.Fn man_deroff +.Fn deroff can be passed to .Xr free 3 . -.It Fn man_meta -Obtain the meta-data of a successful -.Xr man 7 -parse. -This may only be used on a pointer returned by +.It Fn man_validate +Validate the +.Dv MACROSET_MAN +parse tree obtained with .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 -.Xr man 7 -parse. -This may only be used on a pointer returned by +.It Fn mdoc_validate +Validate the +.Dv MACROSET_MDOC +parse tree obtained with .Fn mparse_result . Declared in -.In man.h , -implemented in -.Pa man.c . -.It Fn mdoc_deroff -Obtain a text-only representation of a -.Vt struct mdoc_node , -including text contained in its child nodes. -To be used on children of the pointer returned from -.Fn mdoc_node . -When it is no longer needed, the pointer returned from -.Fn mdoc_deroff -can be passed to -.Xr free 3 . -.It Fn mdoc_meta -Obtain the meta-data of a successful -.Xr mdoc -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 -.Xr mdoc -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: @@ -324,26 +259,26 @@ This is for example useful in .Xr makewhatis 8 .Fl Q to quickly build minimal databases. -.It Ar wlevel -Can be set to -.Dv MANDOCLEVEL_BADARG , -.Dv MANDOCLEVEL_ERROR , +.It Ar os_e +Operating system to check base system conventions for. +If +.Dv MANDOC_OS_OTHER , +the system is automatically detected from +.Ic \&Os , +.Fl Ios , 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 +.Xr uname 3 . +.It Ar os_s A default string for the .Xr mdoc 7 -.Sq \&Os +.Ic \&Os macro, overriding the .Dv OSNAME preprocessor definition and the results of .Xr uname 3 . +Passing +.Dv NULL +sets no default. .El .Pp The same parser may be used for multiple files so long as @@ -362,23 +297,13 @@ 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 . +.It Fn mparse_copy +Dump a copy of the input to the standard output; used for +.Fl man T Ns Cm man . 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_open Open the file for reading. If that fails and @@ -388,9 +313,7 @@ does not already end in try again after appending .Ql .gz . Save the information whether the file is zipped or not. -Return a file descriptor open for reading in -.Fa fd , -or -1 on failure. +Return a file descriptor open for reading or -1 on failure. It can be passed to .Fn mparse_readfd or used directly. @@ -424,34 +347,28 @@ implemented in .Pa read.c . .It Fn mparse_result Obtain the result of a parse. -One of the three pointers will be filled in. +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 .It Va man_macronames -The string representation of a man macro as indexed by +The string representation of a +.Xr man 7 +macro as indexed by .Vt "enum mant" . .It Va mdoc_argnames -The string representation of a mdoc macro argument as indexed by +The string representation of an +.Xr mdoc 7 +macro argument as indexed by .Vt "enum mdocargt" . .It Va mdoc_macronames -The string representation of a mdoc macro as indexed by +The string representation of an +.Xr mdoc 7 +macro as indexed by .Vt "enum mdoct" . .El .Sh IMPLEMENTATION NOTES @@ -495,15 +412,15 @@ This AST is governed by the ontological rules dictated and derives its terminology accordingly. .Pp The AST is composed of -.Vt struct man_node +.Vt struct roff_node nodes with element, root and text types as declared by the .Va type field. Each node also provides its parse point (the .Va line , -.Va sec , +.Va pos , and -.Va pos +.Va sec fields), its position in the tree (the .Va parent , .Va child , @@ -547,20 +464,20 @@ are described simply as .Qq elements . .Pp The AST is composed of -.Vt struct mdoc_node +.Vt struct roff_node nodes with block, head, body, element, root and text types as declared by the .Va type field. Each node also provides its parse point (the .Va line , -.Va sec , +.Va pos , and -.Va pos +.Va sec fields), its position in the tree (the .Va parent , .Va child , -.Va nchild , +.Va last , .Va next and .Va prev @@ -644,10 +561,10 @@ TEXT end .Ed .Pp Here, the formatting of the -.Sq \&Ao +.Ic \&Ao block extends from TEXT ao to TEXT ac, while the formatting of the -.Sq \&Bo +.Ic \&Bo block extends from TEXT bo to TEXT bc. It renders as follows in .Fl T Ns Cm ascii @@ -663,19 +580,21 @@ Using badly-nested blocks is .Em strongly discouraged ; for example, the .Fl T Ns Cm html -and -.Fl T Ns Cm xhtml -front-ends to +front-end to .Xr mandoc 1 -are unable to render them in any meaningful way. +is unable to render them in any meaningful way. Furthermore, behaviour when encountering badly-nested blocks is not consistent across troff implementations, especially when using multiple levels of badly-nested blocks. .Sh SEE ALSO .Xr mandoc 1 , +.Xr man.cgi 3 , .Xr mandoc_escape 3 , +.Xr mandoc_headers 3 , .Xr mandoc_malloc 3 , +.Xr mansearch 3 , .Xr mchars_alloc 3 , +.Xr tbl 3 , .Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , @@ -683,7 +602,10 @@ levels of badly-nested blocks. .Xr roff 7 , .Xr tbl 7 .Sh AUTHORS +.An -nosplit The .Nm library was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org .