update developer documentation

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: 1cbe4572a756539917456c7e9913fa4ba180a719 (patch)
tree: 754b37f3124cbe42ed8c16c979c74856443ce111
parent: b8d5cf8cee9a184753968d5512aa913c9d9d4348 (diff)
download: mandoc-1cbe4572a756539917456c7e9913fa4ba180a719.tar.gz
6 files changed, 200 insertions, 202 deletions
diff --git a/libmandoc.h b/libmandoc.h
index 5a489a32..c00679fd 100644
--- a/libmandoc.h
+++ b/libmandoc.h
@@ -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 df615f18..b7901058 100644
--- a/man.cgi.3
+++ b/man.cgi.3
@@ -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
diff --git a/mandoc.3 b/mandoc.3
index 30135a26..d1471c97 100644
--- a/mandoc.3
+++ b/mandoc.3
@@ -20,13 +20,11 @@
 .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 190432f7..98444224 100644
--- a/mandoc_malloc.3
+++ b/mandoc_malloc.3
@@ -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 cbdf081e..91cf389b 100644
--- a/mchars_alloc.3
+++ b/mchars_alloc.3
@@ -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
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	1cbe4572a756539917456c7e9913fa4ba180a719 (patch)
tree	754b37f3124cbe42ed8c16c979c74856443ce111
parent	b8d5cf8cee9a184753968d5512aa913c9d9d4348 (diff)
download	mandoc-1cbe4572a756539917456c7e9913fa4ba180a719.tar.gz