Return to mandoc.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.26, 2014/09/03 23:21:47 | version 1.38, 2017/01/09 01:37:03 | ||
---|---|---|---|
|
|
||
.\" $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 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_mparse , | ||
.Nm man_node , | .Nm man_validate , | ||
.Nm mdoc_deroff , | .Nm mdoc_validate , | ||
.Nm mdoc_meta , | |||
.Nm mdoc_node , | |||
.Nm mparse_alloc , | .Nm mparse_alloc , | ||
.Nm mparse_free , | .Nm mparse_free , | ||
.Nm mparse_getkeep , | .Nm mparse_getkeep , | ||
|
|
||
.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 LIBRARY | |||
.Lb libmandoc | |||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.In sys/types.h | .In sys/types.h | ||
.In mandoc.h | .In mandoc.h | ||
.Pp | |||
.Fd "#define ASCII_NBRSP" | .Fd "#define ASCII_NBRSP" | ||
.Fd "#define ASCII_HYPH" | .Fd "#define ASCII_HYPH" | ||
.Fd "#define ASCII_BREAK" | .Fd "#define ASCII_BREAK" | ||
|
|
||
.Fo mparse_keep | .Fo mparse_keep | ||
.Fa "struct mparse *parse" | .Fa "struct mparse *parse" | ||
.Fc | .Fc | ||
.Ft "enum mandoclevel" | .Ft int | ||
.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" | ||
.Fa "pid_t *child_pid" | |||
.Fc | .Fc | ||
.Ft "enum mandoclevel" | .Ft "enum mandoclevel" | ||
.Fo mparse_readfd | .Fo mparse_readfd | ||
|
|
||
.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 "pid_t child_pid" | .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 | ||
.Ft void | .Vt extern const char * const * man_macronames; | ||
.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 | |||
.Ft "const struct mparse *" | .Ft "const struct mparse *" | ||
.Fo man_mparse | .Fo man_mparse | ||
.Fa "const struct man *man" | .Fa "const struct roff_man *man" | ||
.Fc | .Fc | ||
.Ft "const struct man_node *" | .Ft void | ||
.Fo man_node | .Fo man_validate | ||
.Fa "const struct man *man" | .Fa "struct roff_man *man" | ||
.Fc | .Fc | ||
.Vt extern const char * const * man_macronames; | |||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm mandoc | .Nm mandoc | ||
|
|
||
.Bl -enum | .Bl -enum | ||
.It | .It | ||
initiate a parsing sequence with | initiate a parsing sequence with | ||
.Xr mchars_alloc 3 | |||
and | |||
.Fn mparse_alloc ; | .Fn mparse_alloc ; | ||
.It | .It | ||
parse files or file descriptors with | open a file with | ||
.Xr open 2 | |||
or | |||
.Fn mparse_open ; | |||
.It | |||
parse it with | |||
.Fn mparse_readfd ; | .Fn mparse_readfd ; | ||
.It | .It | ||
retrieve a parsed syntax tree, if the parse was successful, with | close it with | ||
.Xr close 2 ; | |||
.It | |||
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 | |||
.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 | ||
|
|
||
.Ss Types | .Ss Types | ||
.Bl -ohang | .Bl -ohang | ||
.It Vt "enum mandocerr" | .It Vt "enum mandocerr" | ||
A fatal error, error, or warning message during parsing. | An error or warning message during parsing. | ||
.It Vt "enum mandoclevel" | .It Vt "enum mandoclevel" | ||
A classification of an | A classification of an | ||
.Vt "enum mandocerr" | .Vt "enum mandocerr" | ||
as regards system operation. | as regards system operation. | ||
See the DIAGNOSTICS section in | |||
.Xr mandoc 1 | |||
regarding the meanings of the levels. | |||
.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 | ||
|
|
||
.Fn mparse_reset | .Fn mparse_reset | ||
is called between parses. | is called between parses. | ||
.It Vt "mandocmsg" | .It Vt "mandocmsg" | ||
A prototype for a function to handle fatal error, error, and warning | A prototype for a function to handle error and warning | ||
messages emitted by the parser. | 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 | |||
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 | .It Fn man_mparse | ||
Get the parser used for the current output. | Get the parser used for the current output. | ||
Declared in | Declared in | ||
.In man.h , | .In man.h , | ||
implemented in | implemented in | ||
.Pa man.c . | .Pa man.c . | ||
.It Fn man_node | .It Fn man_validate | ||
Obtain the root node 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 mdoc_deroff | .It Fn mdoc_validate | ||
Obtain a text-only representation of a | Validate the | ||
.Vt struct mdoc_node , | .Dv MACROSET_MDOC | ||
including text contained in its child nodes. | parse tree obtained with | ||
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 . | .Fn mparse_result . | ||
Declared in | 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: | ||
|
|
||
to quickly build minimal databases. | to quickly build minimal databases. | ||
.It Ar wlevel | .It Ar wlevel | ||
Can be set to | Can be set to | ||
.Dv MANDOCLEVEL_FATAL , | .Dv MANDOCLEVEL_BADARG , | ||
.Dv MANDOCLEVEL_ERROR , | .Dv MANDOCLEVEL_ERROR , | ||
or | or | ||
.Dv MANDOCLEVEL_WARNING . | .Dv MANDOCLEVEL_WARNING . | ||
|
|
||
See | See | ||
.Pa main.c | .Pa main.c | ||
for an example. | for an example. | ||
If printing of error messages is not desired, | |||
.Dv NULL | |||
may be passed. | |||
.It Ar defos | .It Ar defos | ||
A default string for the | A default string for the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
.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 | ||
|
|
||
implemented in | implemented in | ||
.Pa read.c . | .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. | ||
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. | ||
If applicable, return the | |||
.Xr gunzip 1 | |||
child process ID in | |||
.Fa child_pid , | |||
or otherwise 0. | |||
If non-zero, it should be passed to | |||
.Fn mparse_wait | |||
after completing the parse sequence. | |||
Declared in | Declared in | ||
.In mandoc.h , | .In mandoc.h , | ||
implemented in | implemented in | ||
.Pa read.c . | .Pa read.c . | ||
.It Fn mparse_readfd | .It Fn mparse_readfd | ||
Parse a file or file descriptor. | Parse a file descriptor opened with | ||
If | .Xr open 2 | ||
.Va fd | or | ||
is -1, | .Fn mparse_open . | ||
.Va fname | Pass the associated filename in | ||
is opened for reading. | .Va fname . | ||
Otherwise, | This function may be called multiple times with different parameters; however, | ||
.Va fname | .Xr close 2 | ||
is assumed to be the name associated with | and | ||
.Va fd . | |||
This may be called multiple times with different parameters; however, | |||
.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. | ||
Only successful parses | One of the two pointers will be filled in. | ||
.Po | |||
i.e., those where | |||
.Fn mparse_readfd | |||
returned less than MANDOCLEVEL_FATAL | |||
.Pc | |||
should invoke this function, in which case one of the three 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 | is higher than | ||
.Fa child_pid | .Pf * Fa rc , | ||
that was spawned with | update | ||
.Fn mparse_open . | .Pf * Fa rc | ||
To be called after the parse sequence is complete. | accordingly. | ||
Returns | This is useful after calling | ||
.Dv MANDOCLEVEL_OK | .Fn mdoc_validate | ||
on success and | or | ||
.Dv MANDOCLEVEL_SYSERR | .Fn man_validate . | ||
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 | ||
|
|
||
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 , | ||
|
|
||
.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 | ||
|
|
||
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 , | ||
|
|
||
.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 . |