From 2d6c4d3de2cb216481f6e9652060cbf6bd0502c2 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Thu, 7 Jul 2016 19:19:01 +0000 Subject: update developer documentation --- libmandoc.h | 3 +- man.cgi.3 | 23 ++++--- mandoc.3 | 185 ++++++++++++++++++++++++++----------------------------- mandoc_headers.3 | 176 +++++++++++++++++++++++++++------------------------- mandoc_malloc.3 | 26 +++----- mchars_alloc.3 | 7 ++- 6 files changed, 209 insertions(+), 211 deletions(-) diff --git a/libmandoc.h b/libmandoc.h index 939ec83c..9ed8f150 100644 --- a/libmandoc.h +++ b/libmandoc.h @@ -1,4 +1,4 @@ -/* $Id: libmandoc.h,v 1.62 2015/11/07 14:01:16 schwarze Exp $ */ +/* $Id: libmandoc.h,v 1.63 2016/07/07 19:19:01 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons * Copyright (c) 2013, 2014, 2015 Ingo Schwarze @@ -38,7 +38,6 @@ struct tbl_span; struct eqn; struct roff; struct roff_man; -struct roff_node; void mandoc_msg(enum mandocerr, struct mparse *, int, int, const char *); diff --git a/man.cgi.3 b/man.cgi.3 index a2b99ad0..e7c1d2fc 100644 --- a/man.cgi.3 +++ b/man.cgi.3 @@ -1,4 +1,4 @@ -.\" $Id: man.cgi.3,v 1.1 2016/04/15 21:16:22 schwarze Exp $ +.\" $Id: man.cgi.3,v 1.2 2016/07/07 19:19:01 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -14,7 +14,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: April 15 2016 $ +.Dd $Mdocdate: July 7 2016 $ .Dt MAN.CGI 3 .Os .Sh NAME @@ -55,14 +55,13 @@ the data directory containing all the manual trees; calls .Fn parse_manpath_conf ; .It -calls -.Fn parse_path_info ; -.It -calls -.Fn parse_query_string if .Ev PATH_INFO -is empty; +is empty, calls +.Fn parse_query_string ; +otherwise, +calls +.Fn parse_path_info ; .It validates the manpath and the architecture; .It @@ -227,9 +226,14 @@ to print the HTTP headers, then prints the HTML header up to the opening tag of the element, then copies the file .Pa header.html to the output, if it exists and is readable. -.It Ft void Fn resp_searchform "const struct req *req" +.It Ft void Fn resp_searchform "const struct req *req" "enum focus focus" This generator prints a search form, filling it with data from the provided request object. +If the +.Fa focus +argument is +.Dv FOCUS_QUERY , +it sets the document's autofocus to the query input box. .It Ft void Fn resp_show "const struct req *req" "const char *file" This wrapper dispatches to either .Fn resp_catman @@ -278,5 +282,6 @@ and does not ascend to parent directories. .Sh SEE ALSO .Xr mandoc 3 , .Xr mansearch 3 , +.Xr mchars_alloc 3 , .Xr mandoc.db 5 , .Xr man.cgi 8 diff --git a/mandoc.3 b/mandoc.3 index 61012ede..18b5707c 100644 --- a/mandoc.3 +++ b/mandoc.3 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.3,v 1.36 2016/01/08 17:48:09 schwarze Exp $ +.\" $Id: mandoc.3,v 1.37 2016/07/07 19:19:01 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010-2016 Ingo Schwarze @@ -15,18 +15,16 @@ .\" 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: July 7 2016 $ .Dt MANDOC 3 .Os .Sh NAME .Nm mandoc , -.Nm man_deroff , -.Nm man_meta , +.Nm deroff , +.Nm mandocmsg , .Nm man_mparse , -.Nm man_node , -.Nm mdoc_deroff , -.Nm mdoc_meta , -.Nm mdoc_node , +.Nm man_validate , +.Nm mdoc_validate , .Nm mparse_alloc , .Nm mparse_free , .Nm mparse_getkeep , @@ -91,8 +89,7 @@ .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 *" @@ -103,45 +100,33 @@ .Fo mparse_strlevel .Fa "enum mandoclevel" .Fc -.In sys/types.h -.In mandoc.h -.In mdoc.h +.In roff.h .Ft void -.Fo mdoc_deroff +.Fo 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" +.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 void -.Fo man_deroff -.Fa "char **dest" -.Fa "const struct man_node *node" -.Fc -.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 @@ -182,10 +167,24 @@ 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 +.Dv MACROSET_MAN , +validate it with +.Fn mdoc_validate or -.Fn man_node ; +.Fn man_validate , +respectively; +.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 @@ -193,7 +192,7 @@ 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 @@ -211,6 +210,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 @@ -226,67 +228,37 @@ 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 -.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 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 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 +.It Fn mdoc_validate +Validate the +.Dv MACROSET_MDOC +parse tree obtained with .Fn mparse_result . Declared in .In mdoc.h , @@ -335,6 +307,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 @@ -343,6 +318,9 @@ 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 @@ -421,7 +399,7 @@ 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 @@ -442,13 +420,19 @@ implemented in .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 @@ -492,15 +476,15 @@ This AST is governed by the ontological rules dictated in 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 , @@ -544,16 +528,16 @@ 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 , @@ -670,9 +654,13 @@ 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 , @@ -680,7 +668,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 . diff --git a/mandoc_headers.3 b/mandoc_headers.3 index 6c30e164..b8c204bb 100644 --- a/mandoc_headers.3 +++ b/mandoc_headers.3 @@ -62,6 +62,11 @@ for .Vt size_t . Provides the utility functions documented in .Xr mandoc_malloc 3 . +.It Qq Pa mandoc_ohash.h +Includes +.In ohash.h +and provides +.Fn mandoc_ohash_init . .It Qq Pa mandoc.h Requires .In sys/types.h @@ -80,7 +85,6 @@ Provides .Vt enum eqn_pilet , .Vt enum eqn_post , .Vt struct tbl_opts , -.Vt struct tbl_head , .Vt struct tbl_cell , .Vt struct tbl_row , .Vt struct tbl_dat , @@ -103,30 +107,30 @@ Uses the opaque type from .Pa read.c for function prototypes. -Uses the types -.Vt struct mdoc -from -.Pa libmdoc.h -and -.Vt struct man +Uses the type +.Vt struct roff_man from -.Pa libman.h -as opaque types for function prototypes. +.Pa roff.h +as an opaque type for function prototypes. .It Qq Pa roff.h Provides .Vt enum mdoc_endbody , +.Vt enum roff_macroset , +.Vt enum roff_next , .Vt enum roff_sec , .Vt enum roff_type , +.Vt struct roff_man , .Vt struct roff_meta , -and -.Vt struct roff_node . +.Vt struct roff_node , +and the function +.Fn deroff . .Pp Uses pointers to the types .Vt struct mdoc_arg and .Vt union mdoc_data from -.Qq Pa mdoc.h +.Pa mdoc.h as opaque struct members. .El .Pp @@ -139,51 +143,38 @@ Afterwards, any other mandoc headers can be included as needed. Requires .In sys/types.h for -.Vt size_t -and -.Qq Pa roff.h -for -.Vt enum roff_type . +.Vt size_t . .Pp Provides .Vt enum mdocargt , -.Vt enum mdoc_disp , -.Vt enum mdoc_list , .Vt enum mdoc_auth , +.Vt enum mdoc_disp , .Vt enum mdoc_font , +.Vt enum mdoc_list , .Vt struct mdoc_argv , .Vt struct mdoc_arg , -.Vt struct mdoc_bd , -.Vt struct mdoc_bl , .Vt struct mdoc_an , +.Vt struct mdoc_bd , .Vt struct mdoc_bf , +.Vt struct mdoc_bl , .Vt struct mdoc_rs , +.Vt union mdoc_data , and the functions .Fn mdoc_* described in .Xr mandoc 3 . .Pp Uses the type -.Vt struct mdoc +.Vt struct roff_man from -.Pa libmdoc.h +.Pa roff.h as an opaque type for function prototypes. -Uses pointers to the types -.Vt struct tbl_span -and -.Vt struct eqn -as opaque struct members. .Pp When this header is included, the same file should not include .Pa libman.h or .Pa libroff.h . .It Qq Pa man.h -Requires -.Qq Pa roff.h -for -.Vt enum roff_type . -.Pp Provides the functions .Fn man_* described in @@ -195,15 +186,10 @@ from .Pa read.c for function prototypes. Uses the type -.Vt struct man +.Vt struct roff_man from -.Pa libman.h +.Pa roff.h as an opaque type for function prototypes. -Uses pointers to the types -.Vt struct tbl_span -and -.Vt struct eqn -as opaque struct members. .Pp When this header is included, the same file should not include .Pa libmdoc.h @@ -220,16 +206,11 @@ are included, the same file should not include any formatter headers. Requires .In sys/types.h for -.Vt size_t , -.Qq Pa mandoc.h -for -.Vt enum mandocerr , +.Vt size_t and -.Qq Pa roff.h +.Qq Pa mandoc.h for -.Vt struct roff_meta -and -.Vt struct roff_node . +.Vt enum mandocerr . .Pp Provides .Vt enum rofferr , @@ -251,14 +232,42 @@ Uses the types and .Vt struct eqn from +.Pa mandoc.h +and +.Vt struct roff_man +from +.Pa roff.h +as opaque types for function prototypes. +.It Qq Pa roff_int.h +Requires +.Qq Pa roff.h +for +.Vt enum roff_type . +.Pp +Provides functions named +.Fn roff_* +to handle roff nodes and the two special functions +.Fn man_breakscope +and +.Fn mdoc_argv_free +because the latter two are needed by +.Qq Pa roff.c . +.Pp +Uses the types +.Vt struct eqn +and +.Vt struct tbl_span +from .Pa mandoc.h , -.Vt struct mdoc +.Vt struct roff_man +and +.Vt struct roff_node from -.Pa libmdoc.h , +.Pa roff.h , and -.Vt struct man +.Vt struct mdoc_arg from -.Pa libman.h +.Pa mdoc.h as opaque types for function prototypes. .It Qq Pa libmdoc.h Requires @@ -269,23 +278,24 @@ and .Vt struct mdoc_* . .Pp Provides -.Vt enum mdoc_next , .Vt enum margserr , .Vt enum mdelim , -.Vt struct mdoc , .Vt struct mdoc_macro , and many functions internal to the .Xr mdoc 7 parser. .Pp -Uses the opaque types +Uses the opaque type .Vt struct mparse from -.Pa read.c +.Pa read.c . +Uses the types +.Vt struct roff_man and -.Vt struct roff +.Vt struct roff_node from -.Pa roff.c . +.Pa roff.h +as opaque types for function prototypes. .Pp When this header is included, the same file should not include .Pa man.h , @@ -293,29 +303,19 @@ When this header is included, the same file should not include or .Pa libroff.h . .It Qq Pa libman.h -Requires -.Qq Pa roff.h -for -.Vt struct roff_meta -and -.Vt struct roff_node . -.Pp Provides -.Vt enum man_next , -.Vt struct man , -.Vt struct man_macro , -and many functions internal to the +.Vt struct man_macro +and some functions internal to the .Xr man 7 parser. .Pp -Uses the opaque types -.Vt struct mparse -from -.Pa read.c +Uses the types +.Vt struct roff_man and -.Vt struct roff +.Vt struct roff_node from -.Pa roff.c . +.Pa roff.h +as opaque types for function prototypes. .Pp When this header is included, the same file should not include .Pa mdoc.h , @@ -420,7 +420,7 @@ from and .Vt struct roff_meta from -.Qq Pa roff.h +.Pa roff.h as opaque types for function prototypes. .Pp When this header is included, the same file should not include @@ -456,18 +456,26 @@ When this header is included, the same file should not include .Pa term.h or .Pa mansearch.h . +.It Qq Pa tag.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides an interface to generate +.Xr ctags 1 +files for the +.Ic :t +functionality mentioned in +.Xr man 1 . .It Qq Pa main.h Provides the top level steering functions for all formatters. .Pp -Uses the types -.Vt struct mdoc -from -.Pa libmdoc.h -and -.Vt struct man +Uses the type +.Vt struct roff_man from -.Pa libman.h -as opaque types for function prototypes. +.Pa roff.h +as an opaque type for function prototypes. .It Qq Pa manconf.h Requires .In sys/types.h diff --git a/mandoc_malloc.3 b/mandoc_malloc.3 index c1679842..ae3ca16a 100644 --- a/mandoc_malloc.3 +++ b/mandoc_malloc.3 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_malloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $ +.\" $Id: mandoc_malloc.3,v 1.2 2016/07/07 19:19:01 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze .\" @@ -14,7 +14,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: August 5 2014 $ +.Dd $Mdocdate: July 7 2016 $ .Dt MANDOC_MALLOC 3 .Os .Sh NAME @@ -26,8 +26,6 @@ .Nm mandoc_strndup , .Nm mandoc_asprintf .Nd memory allocation function wrappers used in the mandoc library -.Sh LIBRARY -.Lb libmandoc .Sh SYNOPSIS .In sys/types.h .In mandoc_aux.h @@ -67,21 +65,18 @@ .Fa "..." .Fc .Sh DESCRIPTION -These functions call the -.Lb libc -functions of the same names, passing through their return values when -successful. +These functions call the libc functions of the same names, passing +through their return values when successful. In case of failure, they do not return, but instead call -.Xr perror 3 -and -.Xr exit 3 . -They can be used both internally by any code in the -.Lb libmandoc +.Xr err 3 . +They can be used both internally by any code in the mandoc libraries and externally by programs using that library, for example .Xr mandoc 1 , +.Xr man 1 , .Xr apropos 1 , +.Xr makewhatis 8 , and -.Xr makewhatis 8 . +.Xr man.cgi 8 . .Pp The function .Fn mandoc_malloc @@ -149,9 +144,8 @@ These functions are implemented in .Pa mandoc_aux.c . .Sh SEE ALSO .Xr asprintf 3 , -.Xr exit 3 , +.Xr err 3 , .Xr malloc 3 , -.Xr perror 3 , .Xr strdup 3 .Sh STANDARDS The functions diff --git a/mchars_alloc.3 b/mchars_alloc.3 index 2d42a432..4bb86208 100644 --- a/mchars_alloc.3 +++ b/mchars_alloc.3 @@ -1,4 +1,4 @@ -.\" $Id: mchars_alloc.3,v 1.3 2015/10/13 22:59:54 schwarze Exp $ +.\" $Id: mchars_alloc.3,v 1.4 2016/07/07 19:19:01 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze .\" @@ -14,7 +14,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: October 13 2015 $ +.Dd $Mdocdate: July 7 2016 $ .Dt MCHARS_ALLOC 3 .Os .Sh NAME @@ -23,7 +23,8 @@ .Nm mchars_num2char , .Nm mchars_num2uc , .Nm mchars_spec2cp , -.Nm mchars_spec2str +.Nm mchars_spec2str , +.Nm mchars_uc2str .Nd character table for mandoc .Sh SYNOPSIS .In sys/types.h -- cgit v1.2.3-56-ge451