diff options
| author |   Ingo Schwarze <schwarze@openbsd.org> | 2016-07-07 19:19:01 +0000 |
|---|---|---|
| committer | Ingo Schwarze <schwarze@openbsd.org> | 2016-07-07 19:19:01 +0000 |
| commit | 2d6c4d3de2cb216481f6e9652060cbf6bd0502c2 (patch) | |
| tree | 9746cb35a59cc42763d440ef179edea64887d5e5 | |
| parent | d2eda06b8199b53e80ec81d6f42c53058999bf7d (diff) | |
| download | mandoc-2d6c4d3de2cb216481f6e9652060cbf6bd0502c2.tar.gz mandoc-2d6c4d3de2cb216481f6e9652060cbf6bd0502c2.tar.zst mandoc-2d6c4d3de2cb216481f6e9652060cbf6bd0502c2.zip | |
update developer documentation
| -rw-r--r-- | libmandoc.h | 3 | ||||
| -rw-r--r-- | man.cgi.3 | 23 | ||||
| -rw-r--r-- | mandoc.3 | 185 | ||||
| -rw-r--r-- | mandoc_headers.3 | 176 | ||||
| -rw-r--r-- | mandoc_malloc.3 | 26 | ||||
| -rw-r--r-- | 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 <kristaps@bsd.lv> * Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> @@ -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 *); @@ -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 <schwarze@openbsd.org> .\" @@ -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 <body> 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 @@ -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 <kristaps@bsd.lv> .\" Copyright (c) 2010-2016 Ingo Schwarze <schwarze@openbsd.org> @@ -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 <schwarze@openbsd.org> .\" @@ -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 <schwarze@openbsd.org> .\" @@ -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 |