summaryrefslogtreecommitdiffstats
path: root/mandoc.3
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2016-07-07 19:19:01 +0000
committerIngo Schwarze <schwarze@openbsd.org>2016-07-07 19:19:01 +0000
commit1cbe4572a756539917456c7e9913fa4ba180a719 (patch)
tree754b37f3124cbe42ed8c16c979c74856443ce111 /mandoc.3
parentb8d5cf8cee9a184753968d5512aa913c9d9d4348 (diff)
downloadmandoc-1cbe4572a756539917456c7e9913fa4ba180a719.tar.gz
update developer documentation
Diffstat (limited to 'mandoc.3')
-rw-r--r--mandoc.3181
1 files changed, 86 insertions, 95 deletions
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 .