* mdocml: update developer documentation
@ 2016-07-07 19:19 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2016-07-07 19:19 UTC (permalink / raw)
To: source
Log Message:
-----------
update developer documentation
Modified Files:
--------------
mdocml:
libmandoc.h
man.cgi.3
mandoc.3
mandoc_headers.3
mandoc_malloc.3
mchars_alloc.3
Revision Data
-------------
Index: mandoc.3
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.3,v
retrieving revision 1.36
retrieving revision 1.37
diff -Lmandoc.3 -Lmandoc.3 -u -p -r1.36 -r1.37
--- mandoc.3
+++ 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 parsi
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
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
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,
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 .
Index: mandoc_malloc.3
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc_malloc.3,v
retrieving revision 1.1
retrieving revision 1.2
diff -Lmandoc_malloc.3 -Lmandoc_malloc.3 -u -p -r1.1 -r1.2
--- mandoc_malloc.3
+++ 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
Index: mandoc_headers.3
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc_headers.3,v
retrieving revision 1.7
retrieving revision 1.8
diff -Lmandoc_headers.3 -Lmandoc_headers.3 -u -p -r1.7 -r1.8
--- mandoc_headers.3
+++ 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
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 i
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 f
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 f
.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
Index: mchars_alloc.3
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mchars_alloc.3,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lmchars_alloc.3 -Lmchars_alloc.3 -u -p -r1.3 -r1.4
--- mchars_alloc.3
+++ 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
Index: man.cgi.3
===================================================================
RCS file: /home/cvs/mdocml/mdocml/man.cgi.3,v
retrieving revision 1.1
retrieving revision 1.2
diff -Lman.cgi.3 -Lman.cgi.3 -u -p -r1.1 -r1.2
--- man.cgi.3
+++ man.cgi.3
@@ -55,14 +55,13 @@ the data directory containing all the ma
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 t
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 directorie
.Sh SEE ALSO
.Xr mandoc 3 ,
.Xr mansearch 3 ,
+.Xr mchars_alloc 3 ,
.Xr mandoc.db 5 ,
.Xr man.cgi 8
Index: libmandoc.h
===================================================================
RCS file: /home/cvs/mdocml/mdocml/libmandoc.h,v
retrieving revision 1.62
retrieving revision 1.63
diff -Llibmandoc.h -Llibmandoc.h -u -p -r1.62 -r1.63
--- libmandoc.h
+++ 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 *);
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2016-07-07 19:19 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-07-07 19:19 mdocml: update developer documentation schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).