version 1.31, 2015/01/15 04:26:40 |
version 1.42, 2018/08/23 19:33:27 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm mandoc , |
.Nm mandoc , |
.Nm man_deroff , |
.Nm deroff , |
.Nm man_meta , |
.Nm mandocmsg , |
.Nm man_mparse , |
.Nm man_validate , |
.Nm man_node , |
.Nm mdoc_validate , |
.Nm mdoc_deroff , |
|
.Nm mdoc_meta , |
|
.Nm mdoc_node , |
|
.Nm mparse_alloc , |
.Nm mparse_alloc , |
|
.Nm mparse_copy , |
.Nm mparse_free , |
.Nm mparse_free , |
.Nm mparse_getkeep , |
|
.Nm mparse_keep , |
|
.Nm mparse_open , |
.Nm mparse_open , |
.Nm mparse_readfd , |
.Nm mparse_readfd , |
.Nm mparse_reset , |
.Nm mparse_reset , |
.Nm mparse_result , |
.Nm mparse_result , |
.Nm mparse_strerror , |
.Nm mparse_strerror , |
.Nm mparse_strlevel |
.Nm mparse_strlevel , |
.Nm mparse_wait , |
.Nm mparse_updaterc |
.Nd mandoc macro compiler library |
.Nd mandoc macro compiler library |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In sys/types.h |
.In sys/types.h |
|
|
.Ft struct mparse * |
.Ft struct mparse * |
.Fo mparse_alloc |
.Fo mparse_alloc |
.Fa "int options" |
.Fa "int options" |
.Fa "enum mandoclevel wlevel" |
.Fa "enum mandocerr mmin" |
.Fa "mandocmsg mmsg" |
.Fa "mandocmsg mmsg" |
.Fa "const struct mchars *mchars" |
.Fa "enum mandoc_os oe_e" |
.Fa "char *defos" |
.Fa "char *os_s" |
.Fc |
.Fc |
.Ft void |
.Ft void |
.Fo (*mandocmsg) |
.Fo (*mandocmsg) |
|
|
.Fo mparse_free |
.Fo mparse_free |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fc |
.Fc |
.Ft const char * |
.Ft void |
.Fo mparse_getkeep |
.Fo mparse_copy |
.Fa "const struct mparse *parse" |
.Fa "const struct mparse *parse" |
.Fc |
.Fc |
.Ft void |
.Ft int |
.Fo mparse_keep |
|
.Fa "struct mparse *parse" |
|
.Fc |
|
.Ft "enum mandoclevel" |
|
.Fo mparse_open |
.Fo mparse_open |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fa "int *fd" |
|
.Fa "const char *fname" |
.Fa "const char *fname" |
.Fc |
.Fc |
.Ft "enum mandoclevel" |
.Ft "enum mandoclevel" |
|
|
.Ft void |
.Ft void |
.Fo mparse_result |
.Fo mparse_result |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fa "struct mdoc **mdoc" |
.Fa "struct roff_man **man" |
.Fa "struct man **man" |
|
.Fa "char **sodest" |
.Fa "char **sodest" |
.Fc |
.Fc |
.Ft "const char *" |
.Ft "const char *" |
|
|
.Fo mparse_strlevel |
.Fo mparse_strlevel |
.Fa "enum mandoclevel" |
.Fa "enum mandoclevel" |
.Fc |
.Fc |
.Ft "enum mandoclevel" |
.Ft void |
.Fo mparse_wait |
.Fo mparse_updaterc |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
|
.Fa "enum mandoclevel *rc" |
.Fc |
.Fc |
.In sys/types.h |
.In roff.h |
.In mandoc.h |
|
.In mdoc.h |
|
.Ft void |
.Ft void |
.Fo mdoc_deroff |
.Fo deroff |
.Fa "char **dest" |
.Fa "char **dest" |
.Fa "const struct mdoc_node *node" |
.Fa "const struct roff_node *node" |
.Fc |
.Fc |
.Ft "const struct mdoc_meta *" |
.In sys/types.h |
.Fo mdoc_meta |
.In mandoc.h |
.Fa "const struct mdoc *mdoc" |
.In mdoc.h |
.Fc |
|
.Ft "const struct mdoc_node *" |
|
.Fo mdoc_node |
|
.Fa "const struct mdoc *mdoc" |
|
.Fc |
|
.Vt extern const char * const * mdoc_argnames; |
.Vt extern const char * const * mdoc_argnames; |
.Vt extern const char * const * mdoc_macronames; |
.Vt extern const char * const * mdoc_macronames; |
|
.Ft void |
|
.Fo mdoc_validate |
|
.Fa "struct roff_man *mdoc" |
|
.Fc |
.In sys/types.h |
.In sys/types.h |
.In mandoc.h |
.In mandoc.h |
.In man.h |
.In man.h |
|
.Vt extern const char * const * man_macronames; |
.Ft void |
.Ft void |
.Fo man_deroff |
.Fo man_validate |
.Fa "char **dest" |
.Fa "struct roff_man *man" |
.Fa "const struct man_node *node" |
|
.Fc |
.Fc |
.Ft "const struct man_meta *" |
|
.Fo man_meta |
|
.Fa "const struct man *man" |
|
.Fc |
|
.Ft "const struct mparse *" |
|
.Fo man_mparse |
|
.Fa "const struct man *man" |
|
.Fc |
|
.Ft "const struct man_node *" |
|
.Fo man_node |
|
.Fa "const struct man *man" |
|
.Fc |
|
.Vt extern const char * const * man_macronames; |
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm mandoc |
.Nm mandoc |
|
|
parse it with |
parse it with |
.Fn mparse_readfd ; |
.Fn mparse_readfd ; |
.It |
.It |
|
close it with |
|
.Xr close 2 ; |
|
.It |
retrieve the syntax tree with |
retrieve the syntax tree with |
.Fn mparse_result ; |
.Fn mparse_result ; |
.It |
.It |
iterate over parse nodes with |
depending on whether the |
.Fn mdoc_node |
.Fa macroset |
|
member of the returned |
|
.Vt struct roff_man |
|
is |
|
.Dv MACROSET_MDOC |
or |
or |
.Fn man_node ; |
.Dv MACROSET_MAN , |
|
validate it with |
|
.Fn mdoc_validate |
|
or |
|
.Fn man_validate , |
|
respectively; |
.It |
.It |
|
if information about the validity of the input is needed, fetch it with |
|
.Fn mparse_updaterc ; |
|
.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 |
free all allocated memory with |
.Fn mparse_free |
.Fn mparse_free |
and |
and |
.Xr mchars_free 3 , |
.Xr mchars_free 3 , |
or invoke |
or invoke |
.Fn mparse_reset |
.Fn mparse_reset |
and parse new files. |
and go back to step 2 to parse new files. |
.El |
.El |
.Sh REFERENCE |
.Sh REFERENCE |
This section documents the functions, types, and variables available |
This section documents the functions, types, and variables available |
Line 215 An error or warning message during parsing. |
|
Line 210 An error or warning message during parsing. |
|
A classification of an |
A classification of an |
.Vt "enum mandocerr" |
.Vt "enum mandocerr" |
as regards system operation. |
as regards system operation. |
.It Vt "struct mchars" |
See the DIAGNOSTICS section in |
An opaque pointer to a a character table. |
.Xr mandoc 1 |
Created with |
regarding the meanings of the levels. |
.Xr mchars_alloc 3 |
|
and freed with |
|
.Xr mchars_free 3 . |
|
.It Vt "struct mparse" |
.It Vt "struct mparse" |
An opaque pointer to a running parse sequence. |
An opaque pointer to a running parse sequence. |
Created with |
Created with |
Line 236 messages emitted by the parser. |
|
Line 228 messages emitted by the parser. |
|
.El |
.El |
.Ss Functions |
.Ss Functions |
.Bl -ohang |
.Bl -ohang |
.It Fn man_deroff |
.It Fn deroff |
Obtain a text-only representation of a |
Obtain a text-only representation of a |
.Vt struct man_node , |
.Vt struct roff_node , |
including text contained in its child nodes. |
including text contained in its child nodes. |
To be used on children of the pointer returned from |
To be used on children of the |
.Fn man_node . |
.Fa first |
|
member of |
|
.Vt struct roff_man . |
When it is no longer needed, the pointer returned from |
When it is no longer needed, the pointer returned from |
.Fn man_deroff |
.Fn deroff |
can be passed to |
can be passed to |
.Xr free 3 . |
.Xr free 3 . |
.It Fn man_meta |
.It Fn man_validate |
Obtain the meta-data of a successful |
Validate the |
.Xr man 7 |
.Dv MACROSET_MAN |
parse. |
parse tree obtained with |
This may only be used on a pointer returned by |
|
.Fn mparse_result . |
.Fn mparse_result . |
Declared in |
Declared in |
.In man.h , |
.In man.h , |
implemented in |
implemented in |
.Pa man.c . |
.Pa man.c . |
.It Fn man_mparse |
.It Fn mdoc_validate |
Get the parser used for the current output. |
Validate the |
Declared in |
.Dv MACROSET_MDOC |
.In man.h , |
parse tree obtained with |
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 |
|
.Fn mparse_result . |
.Fn mparse_result . |
Declared in |
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 , |
.In mdoc.h , |
implemented in |
implemented in |
.Pa mdoc.c . |
.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 |
|
.Fn mparse_result . |
|
Declared in |
|
.In mdoc.h , |
|
implemented in |
|
.Pa mdoc.c . |
|
.It Fn mparse_alloc |
.It Fn mparse_alloc |
Allocate a parser. |
Allocate a parser. |
The arguments have the following effect: |
The arguments have the following effect: |
Line 333 This is for example useful in |
|
Line 289 This is for example useful in |
|
.Xr makewhatis 8 |
.Xr makewhatis 8 |
.Fl Q |
.Fl Q |
to quickly build minimal databases. |
to quickly build minimal databases. |
.It Ar wlevel |
.It Ar mmin |
Can be set to |
Can be set to |
.Dv MANDOCLEVEL_BADARG , |
.Dv MANDOCERR_BASE , |
.Dv MANDOCLEVEL_ERROR , |
.Dv MANDOCERR_STYLE , |
|
.Dv MANDOCERR_WARNING , |
|
.Dv MANDOCERR_ERROR , |
|
.Dv MANDOCERR_UNSUPP , |
or |
or |
.Dv MANDOCLEVEL_WARNING . |
.Dv MANDOCERR_MAX . |
Messages below the selected level will be suppressed. |
Messages below the selected level will be suppressed. |
.It Ar mmsg |
.It Ar mmsg |
A callback function to handle errors and warnings. |
A callback function to handle errors and warnings. |
See |
See |
.Pa main.c |
.Pa main.c |
for an example. |
for an example. |
.It Ar mchars |
If printing of error messages is not desired, |
An opaque pointer to a a character table obtained from |
.Dv NULL |
.Xr mchars_alloc 3 . |
may be passed. |
.It Ar defos |
.It Ar os_e |
|
Operating system to check base system conventions for. |
|
If |
|
.Dv MANDOC_OS_OTHER , |
|
the system is automatically detected from |
|
.Ic \&Os , |
|
.Fl Ios , |
|
or |
|
.Xr uname 3 . |
|
.It Ar os_s |
A default string for the |
A default string for the |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sq \&Os |
.Ic \&Os |
macro, overriding the |
macro, overriding the |
.Dv OSNAME |
.Dv OSNAME |
preprocessor definition and the results of |
preprocessor definition and the results of |
.Xr uname 3 . |
.Xr uname 3 . |
|
Passing |
|
.Dv NULL |
|
sets no default. |
.El |
.El |
.Pp |
.Pp |
The same parser may be used for multiple files so long as |
The same parser may be used for multiple files so long as |
|
|
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.Pa read.c . |
.It Fn mparse_getkeep |
.It Fn mparse_copy |
Acquire the keep buffer. |
Dump a copy of the input to the standard output; used for |
Must follow a call of |
.Fl man T Ns Cm man . |
.Fn mparse_keep . |
|
Declared in |
Declared in |
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.Pa read.c . |
.It Fn mparse_keep |
|
Instruct the parser to retain a copy of its parsed input. |
|
This can be acquired with subsequent |
|
.Fn mparse_getkeep |
|
calls. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
|
.It Fn mparse_open |
.It Fn mparse_open |
If the |
Open the file for reading. |
|
If that fails and |
.Fa fname |
.Fa fname |
ends in |
does not already end in |
.Pa .gz , |
.Ql .gz , |
open with |
try again after appending |
.Xr gunzip 1 ; |
.Ql .gz . |
otherwise, with |
Save the information whether the file is zipped or not. |
.Xr open 2 . |
Return a file descriptor open for reading or -1 on failure. |
If |
|
.Xr open 2 |
|
fails, append |
|
.Pa .gz |
|
and try with |
|
.Xr gunzip 1 . |
|
Return a file descriptor open for reading in |
|
.Fa fd , |
|
or -1 on failure. |
|
It can be passed to |
It can be passed to |
.Fn mparse_readfd |
.Fn mparse_readfd |
or used directly. |
or used directly. |
|
|
.Fn mparse_open . |
.Fn mparse_open . |
Pass the associated filename in |
Pass the associated filename in |
.Va fname . |
.Va fname . |
Calls |
|
.Fn mparse_wait |
|
before returning. |
|
This function may be called multiple times with different parameters; however, |
This function may be called multiple times with different parameters; however, |
|
.Xr close 2 |
|
and |
.Fn mparse_reset |
.Fn mparse_reset |
should be invoked between parses. |
should be invoked between parses. |
Declared in |
Declared in |
|
|
.Pa read.c . |
.Pa read.c . |
.It Fn mparse_result |
.It Fn mparse_result |
Obtain the result of a parse. |
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 |
Declared in |
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
|
|
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.Pa read.c . |
.It Fn mparse_wait |
.It Fn mparse_updaterc |
Bury a |
If the highest warning or error level that occurred during the current |
.Xr gunzip 1 |
.Fa parse |
child process that was spawned with |
is higher than |
.Fn mparse_open . |
.Pf * Fa rc , |
To be called after the parse sequence is complete. |
update |
Not needed after |
.Pf * Fa rc |
.Fn mparse_readfd , |
accordingly. |
but does no harm in that case, either. |
This is useful after calling |
Returns |
.Fn mdoc_validate |
.Dv MANDOCLEVEL_OK |
or |
on success and |
.Fn man_validate . |
.Dv MANDOCLEVEL_SYSERR |
|
on failure, that is, when |
|
.Xr wait 2 |
|
fails, or when |
|
.Xr gunzip 1 |
|
died from a signal or exited with non-zero status. |
|
Declared in |
Declared in |
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
|
|
.Ss Variables |
.Ss Variables |
.Bl -ohang |
.Bl -ohang |
.It Va man_macronames |
.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" . |
.Vt "enum mant" . |
.It Va mdoc_argnames |
.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" . |
.Vt "enum mdocargt" . |
.It Va mdoc_macronames |
.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" . |
.Vt "enum mdoct" . |
.El |
.El |
.Sh IMPLEMENTATION NOTES |
.Sh IMPLEMENTATION NOTES |
Line 536 This AST is governed by the ontological rules dictated |
|
Line 488 This AST is governed by the ontological rules dictated |
|
and derives its terminology accordingly. |
and derives its terminology accordingly. |
.Pp |
.Pp |
The AST is composed of |
The AST is composed of |
.Vt struct man_node |
.Vt struct roff_node |
nodes with element, root and text types as declared by the |
nodes with element, root and text types as declared by the |
.Va type |
.Va type |
field. |
field. |
Each node also provides its parse point (the |
Each node also provides its parse point (the |
.Va line , |
.Va line , |
.Va sec , |
.Va pos , |
and |
and |
.Va pos |
.Va sec |
fields), its position in the tree (the |
fields), its position in the tree (the |
.Va parent , |
.Va parent , |
.Va child , |
.Va child , |
Line 588 are described simply as |
|
Line 540 are described simply as |
|
.Qq elements . |
.Qq elements . |
.Pp |
.Pp |
The AST is composed of |
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 |
nodes with block, head, body, element, root and text types as declared |
by the |
by the |
.Va type |
.Va type |
field. |
field. |
Each node also provides its parse point (the |
Each node also provides its parse point (the |
.Va line , |
.Va line , |
.Va sec , |
.Va pos , |
and |
and |
.Va pos |
.Va sec |
fields), its position in the tree (the |
fields), its position in the tree (the |
.Va parent , |
.Va parent , |
.Va child , |
.Va child , |
.Va nchild , |
.Va last , |
.Va next |
.Va next |
and |
and |
.Va prev |
.Va prev |
|
|
.Ed |
.Ed |
.Pp |
.Pp |
Here, the formatting of the |
Here, the formatting of the |
.Sq \&Ao |
.Ic \&Ao |
block extends from TEXT ao to TEXT ac, |
block extends from TEXT ao to TEXT ac, |
while the formatting of the |
while the formatting of the |
.Sq \&Bo |
.Ic \&Bo |
block extends from TEXT bo to TEXT bc. |
block extends from TEXT bo to TEXT bc. |
It renders as follows in |
It renders as follows in |
.Fl T Ns Cm ascii |
.Fl T Ns Cm ascii |
Line 704 Using badly-nested blocks is |
|
Line 656 Using badly-nested blocks is |
|
.Em strongly discouraged ; |
.Em strongly discouraged ; |
for example, the |
for example, the |
.Fl T Ns Cm html |
.Fl T Ns Cm html |
and |
front-end to |
.Fl T Ns Cm xhtml |
|
front-ends to |
|
.Xr mandoc 1 |
.Xr mandoc 1 |
are unable to render them in any meaningful way. |
is unable to render them in any meaningful way. |
Furthermore, behaviour when encountering badly-nested blocks is not |
Furthermore, behaviour when encountering badly-nested blocks is not |
consistent across troff implementations, especially when using multiple |
consistent across troff implementations, especially when using multiple |
levels of badly-nested blocks. |
levels of badly-nested blocks. |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
|
.Xr man.cgi 3 , |
.Xr mandoc_escape 3 , |
.Xr mandoc_escape 3 , |
|
.Xr mandoc_headers 3 , |
.Xr mandoc_malloc 3 , |
.Xr mandoc_malloc 3 , |
|
.Xr mansearch 3 , |
.Xr mchars_alloc 3 , |
.Xr mchars_alloc 3 , |
|
.Xr tbl 3 , |
.Xr eqn 7 , |
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 , |
.Xr mandoc_char 7 , |
Line 724 levels of badly-nested blocks. |
|
Line 678 levels of badly-nested blocks. |
|
.Xr roff 7 , |
.Xr roff 7 , |
.Xr tbl 7 |
.Xr tbl 7 |
.Sh AUTHORS |
.Sh AUTHORS |
|
.An -nosplit |
The |
The |
.Nm |
.Nm |
library was written by |
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 . |