=================================================================== RCS file: /cvs/mandoc/mandoc.3,v retrieving revision 1.24 retrieving revision 1.38 diff -u -p -r1.24 -r1.38 --- mandoc/mandoc.3 2014/03/23 11:25:26 1.24 +++ mandoc/mandoc.3 2017/01/09 01:37:03 1.38 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.3,v 1.24 2014/03/23 11:25:26 schwarze Exp $ +.\" $Id: mandoc.3,v 1.38 2017/01/09 01:37:03 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2010 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,92 +15,41 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 23 2014 $ +.Dd $Mdocdate: January 9 2017 $ .Dt MANDOC 3 .Os .Sh NAME .Nm mandoc , -.Nm mandoc_calloc , -.Nm mandoc_escape , -.Nm mandoc_malloc , -.Nm mandoc_realloc , -.Nm mandoc_strdup , -.Nm mandoc_strndup , -.Nm man_meta , +.Nm deroff , +.Nm mandocmsg , .Nm man_mparse , -.Nm man_node , -.Nm mchars_alloc , -.Nm mchars_free , -.Nm mchars_num2char , -.Nm mchars_num2uc , -.Nm mchars_spec2cp , -.Nm mchars_spec2str , -.Nm mdoc_meta , -.Nm mdoc_node , +.Nm man_validate , +.Nm mdoc_validate , .Nm mparse_alloc , .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_strlevel , +.Nm mparse_updaterc .Nd mandoc macro compiler library -.Sh LIBRARY -.Lb libmandoc .Sh SYNOPSIS +.In sys/types.h .In mandoc.h +.Pp .Fd "#define ASCII_NBRSP" .Fd "#define ASCII_HYPH" .Fd "#define ASCII_BREAK" -.Ft "void *" -.Fo mandoc_calloc -.Fa "size_t nmemb" -.Fa "size_t size" -.Fc -.Ft "enum mandoc_esc" -.Fo mandoc_escape -.Fa "const char **end" -.Fa "const char **start" -.Fa "int *sz" -.Fc -.Ft "void *" -.Fn mandoc_malloc "size_t size" -.Ft "struct mchars *" -.Fo mandoc_realloc -.Fa "void *ptr" -.Fa "size_t size" -.Fc -.Ft "char *" -.Fn mandoc_strdup -.Fn mchars_alloc "void" -.Ft void -.Fn mchars_free "struct mchars *p" -.Ft char -.Fn mchars_num2char "const char *cp" "size_t sz" -.Ft int -.Fn mchars_num2uc "const char *cp" "size_t sz" -.Ft "const char *" -.Fo mchars_spec2str -.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 struct mchars *p" -.Fa "const char *cp" -.Fa "size_t sz" -.Fc -.Ft void +.Ft struct mparse * .Fo mparse_alloc -.Fa "enum mparset inttype" +.Fa "int options" .Fa "enum mandoclevel wlevel" .Fa "mandocmsg mmsg" .Fa "char *defos" -.Fa "int quick" .Fc .Ft void .Fo (*mandocmsg) @@ -123,6 +72,11 @@ .Fo mparse_keep .Fa "struct mparse *parse" .Fc +.Ft int +.Fo mparse_open +.Fa "struct mparse *parse" +.Fa "const char *fname" +.Fc .Ft "enum mandoclevel" .Fo mparse_readfd .Fa "struct mparse *parse" @@ -136,8 +90,8 @@ .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 @@ -147,33 +101,38 @@ .Fo mparse_strlevel .Fa "enum mandoclevel" .Fc -.In mandoc.h -.In mdoc.h -.Ft "const struct mdoc_meta *" -.Fo mdoc_meta -.Fa "const struct mdoc *mdoc" +.Ft void +.Fo mparse_updaterc +.Fa "struct mparse *parse" +.Fa "enum mandoclevel *rc" .Fc -.Ft "const struct mdoc_node *" -.Fo mdoc_node -.Fa "const struct mdoc *mdoc" +.In roff.h +.Ft void +.Fo deroff +.Fa "char **dest" +.Fa "const struct roff_node *node" .Fc +.In sys/types.h +.In mandoc.h +.In mdoc.h .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 -.Ft "const struct man_meta *" -.Fo man_meta -.Fa "const struct man *man" -.Fc +.Vt extern const char * const * man_macronames; .Ft "const struct mparse *" .Fo man_mparse -.Fa "const struct man *man" +.Fa "const struct roff_man *man" .Fc -.Ft "const struct man_node *" -.Fo man_node -.Fa "const struct man *man" +.Ft void +.Fo man_validate +.Fa "struct roff_man *man" .Fc -.Vt extern const char * const * man_macronames; .Sh DESCRIPTION The .Nm mandoc @@ -196,56 +155,73 @@ The following describes a general parse sequence: .Bl -enum .It initiate a parsing sequence with +.Xr mchars_alloc 3 +and .Fn mparse_alloc ; .It -parse files or file descriptors with +open a file with +.Xr open 2 +or +.Fn mparse_open ; +.It +parse it with .Fn mparse_readfd ; .It -retrieve a parsed syntax tree, if the parse was successful, with +close it with +.Xr close 2 ; +.It +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 , +.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 -.Pp -The -.Nm -library also contains routines for translating character strings into glyphs -.Pq see Fn mchars_alloc -and parsing escape sequences from strings -.Pq see Fn mandoc_escape . .Sh REFERENCE This section documents the functions, types, and variables available via -.In mandoc.h . +.In mandoc.h , +with the exception of those documented in +.Xr mandoc_escape 3 +and +.Xr mchars_alloc 3 . .Ss Types .Bl -ohang -.It Vt "enum mandoc_esc" -An escape sequence classification. .It Vt "enum mandocerr" -A fatal error, error, or warning message during parsing. +An error or warning message during parsing. .It Vt "enum mandoclevel" A classification of an .Vt "enum mandocerr" as regards system operation. -.It Vt "struct mchars" -An opaque pointer to an object allowing for translation between -character strings and glyphs. -See -.Fn mchars_alloc . -.It Vt "enum mparset" -The type of parser when reading input. -This should usually be -.Dv MPARSE_AUTO -for auto-detection. +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 @@ -256,147 +232,81 @@ 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 fatal error, error, and warning +A prototype for a function to handle error and warning messages emitted by the parser. .El .Ss Functions .Bl -ohang -.It Fn mandoc_escape -Scan an escape sequence, i.e., a character string beginning with -.Sq \e . -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 -.Dv ESCAPE_ERROR , -in which case the string is bogus and should be -thrown away. -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 -.Va sz . -Both -.Va start -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 deroff +Obtain a text-only representation of a +.Vt struct roff_node , +including text contained in its child nodes. +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 deroff +can be passed to +.Xr free 3 . .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 +.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 mchars_alloc -Allocate an -.Vt "struct mchars *" -object for translating special characters into glyphs. -See -.Xr mandoc_char 7 -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 +.It Fn mdoc_validate +Validate the +.Dv MACROSET_MDOC +parse tree obtained with .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 +.It Ar options +When the .Dv MPARSE_MDOC or -.Dv MPARSE_MAN , -only that parser will be used. -With -.Dv MPARSE_AUTO , -the document type will be automatically detected. +.Dv MPARSE_MAN +bit is set, only that parser is used. +Otherwise, the document type is automatically detected. +.Pp +When the +.Dv MPARSE_SO +bit is set, +.Xr roff 7 +.Ic \&so +file inclusion requests are always honoured. +Otherwise, if the request is the only content in an input file, +only the file name is remembered, to be returned in the +.Fa sodest +argument of +.Fn mparse_result . +.Pp +When the +.Dv MPARSE_QUICK +bit is set, parsing is aborted after the NAME section. +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_FATAL , +.Dv MANDOCLEVEL_BADARG , .Dv MANDOCLEVEL_ERROR , or .Dv MANDOCLEVEL_WARNING . @@ -406,6 +316,9 @@ A callback function to handle errors and warnings. See .Pa main.c for an example. +If printing of error messages is not desired, +.Dv NULL +may be passed. .It Ar defos A default string for the .Xr mdoc 7 @@ -414,9 +327,9 @@ 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. +Passing +.Dv NULL +sets no default. .El .Pp The same parser may be used for multiple files so long as @@ -452,18 +365,33 @@ Declared in .In mandoc.h , implemented in .Pa read.c . +.It Fn mparse_open +Open the file for reading. +If that fails and +.Fa fname +does not already end in +.Ql .gz , +try again after appending +.Ql .gz . +Save the information whether the file is zipped or not. +Return a file descriptor open for reading or -1 on failure. +It can be passed to +.Fn mparse_readfd +or used directly. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . .It Fn mparse_readfd -Parse a file or file descriptor. -If -.Va fd -is -1, -.Va fname -is opened for reading. -Otherwise, -.Va fname -is assumed to be the name associated with -.Va fd . -This may be called multiple times with different parameters; however, +Parse a file descriptor opened with +.Xr open 2 +or +.Fn mparse_open . +Pass the associated filename in +.Va fname . +This function may be called multiple times with different parameters; however, +.Xr close 2 +and .Fn mparse_reset should be invoked between parses. Declared in @@ -480,14 +408,7 @@ implemented in .Pa read.c . .It Fn mparse_result Obtain the result of a parse. -Only successful parses -.Po -i.e., those where -.Fn mparse_readfd -returned less than MANDOCLEVEL_FATAL -.Pc -should invoke this function, in which case one of the two pointers will -be filled in. +One of the two pointers will be filled in. Declared in .In mandoc.h , implemented in @@ -504,17 +425,39 @@ Declared in .In mandoc.h , implemented in .Pa read.c . +.It Fn mparse_updaterc +If the highest warning or error level that occurred during the current +.Fa parse +is higher than +.Pf * Fa rc , +update +.Pf * Fa rc +accordingly. +This is useful after calling +.Fn mdoc_validate +or +.Fn man_validate . +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 @@ -540,6 +483,8 @@ The following non-printing characters may be embedded A non-breaking space character. .It Dv ASCII_HYPH A soft hyphen. +.It Dv ASCII_BREAK +A breakable zero-width space. .El .Pp Escape characters are also passed verbatim into text strings. @@ -547,26 +492,24 @@ An escape character is a sequence of characters beginn backslash .Pq Sq \e . To construct human-readable text, these should be intercepted with -.Fn mandoc_escape -and converted with one of -.Fn mchars_num2char , -.Fn mchars_spec2str , -and so on. +.Xr mandoc_escape 3 +and converted with one the functions described in +.Xr mchars_alloc 3 . .Ss Man Abstract Syntax Tree This AST is governed by the ontological rules dictated in .Xr man 7 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 , @@ -596,7 +539,7 @@ where capitalised non-terminals represent nodes. .El .Pp The only elements capable of nesting other elements are those with -next-lint scope as documented in +next-line scope as documented in .Xr man 7 . .Ss Mdoc Abstract Syntax Tree This AST is governed by the ontological @@ -610,20 +553,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 @@ -732,10 +675,17 @@ front-ends to .Xr mandoc 1 are 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 +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 , @@ -743,7 +693,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 .