Return to mandoc.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.24, 2014/03/23 11:25:26 | version 1.29, 2014/11/26 23:42:14 | ||
---|---|---|---|
|
|
||
.Os | .Os | ||
.Sh NAME | .Sh NAME | ||
.Nm mandoc , | .Nm mandoc , | ||
.Nm mandoc_calloc , | .Nm man_deroff , | ||
.Nm mandoc_escape , | |||
.Nm mandoc_malloc , | |||
.Nm mandoc_realloc , | |||
.Nm mandoc_strdup , | |||
.Nm mandoc_strndup , | |||
.Nm man_meta , | .Nm man_meta , | ||
.Nm man_mparse , | .Nm man_mparse , | ||
.Nm man_node , | .Nm man_node , | ||
.Nm mchars_alloc , | .Nm mdoc_deroff , | ||
.Nm mchars_free , | |||
.Nm mchars_num2char , | |||
.Nm mchars_num2uc , | |||
.Nm mchars_spec2cp , | |||
.Nm mchars_spec2str , | |||
.Nm mdoc_meta , | .Nm mdoc_meta , | ||
.Nm mdoc_node , | .Nm mdoc_node , | ||
.Nm mparse_alloc , | .Nm mparse_alloc , | ||
.Nm mparse_free , | .Nm mparse_free , | ||
.Nm mparse_getkeep , | .Nm mparse_getkeep , | ||
.Nm mparse_keep , | .Nm mparse_keep , | ||
.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 , | |||
.Nd mandoc macro compiler library | .Nd mandoc macro compiler library | ||
.Sh LIBRARY | .Sh LIBRARY | ||
.Lb libmandoc | .Lb libmandoc | ||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.In sys/types.h | |||
.In mandoc.h | .In mandoc.h | ||
.Fd "#define ASCII_NBRSP" | .Fd "#define ASCII_NBRSP" | ||
.Fd "#define ASCII_HYPH" | .Fd "#define ASCII_HYPH" | ||
.Fd "#define ASCII_BREAK" | .Fd "#define ASCII_BREAK" | ||
.Ft "void *" | .Ft struct mparse * | ||
.Fo mandoc_calloc | |||
.Fa "size_t nmemb" | |||
.Fa "size_t size" | |||
.Fc | |||
.Ft "enum mandoc_esc" | |||
.Fo mandoc_escape | |||
.Fa "const char **end" | |||
.Fa "const char **start" | |||
.Fa "int *sz" | |||
.Fc | |||
.Ft "void *" | |||
.Fn mandoc_malloc "size_t size" | |||
.Ft "struct mchars *" | |||
.Fo mandoc_realloc | |||
.Fa "void *ptr" | |||
.Fa "size_t size" | |||
.Fc | |||
.Ft "char *" | |||
.Fn mandoc_strdup | |||
.Fn mchars_alloc "void" | |||
.Ft void | |||
.Fn mchars_free "struct mchars *p" | |||
.Ft char | |||
.Fn mchars_num2char "const char *cp" "size_t sz" | |||
.Ft int | |||
.Fn mchars_num2uc "const char *cp" "size_t sz" | |||
.Ft "const char *" | |||
.Fo mchars_spec2str | |||
.Fa "const struct mchars *p" | |||
.Fa "const char *cp" | |||
.Fa "size_t sz" | |||
.Fa "size_t *rsz" | |||
.Fc | |||
.Ft int | |||
.Fo mchars_spec2cp | |||
.Fa "const struct mchars *p" | |||
.Fa "const char *cp" | |||
.Fa "size_t sz" | |||
.Fc | |||
.Ft void | |||
.Fo mparse_alloc | .Fo mparse_alloc | ||
.Fa "enum mparset inttype" | .Fa "int options" | ||
.Fa "enum mandoclevel wlevel" | .Fa "enum mandoclevel wlevel" | ||
.Fa "mandocmsg mmsg" | .Fa "mandocmsg mmsg" | ||
.Fa "const struct mchars *mchars" | |||
.Fa "char *defos" | .Fa "char *defos" | ||
.Fa "int quick" | |||
.Fc | .Fc | ||
.Ft void | .Ft void | ||
.Fo (*mandocmsg) | .Fo (*mandocmsg) | ||
|
|
||
.Fa "struct mparse *parse" | .Fa "struct mparse *parse" | ||
.Fc | .Fc | ||
.Ft "enum mandoclevel" | .Ft "enum mandoclevel" | ||
.Fo mparse_open | |||
.Fa "struct mparse *parse" | |||
.Fa "int *fd" | |||
.Fa "const char *fname" | |||
.Fc | |||
.Ft "enum mandoclevel" | |||
.Fo mparse_readfd | .Fo mparse_readfd | ||
.Fa "struct mparse *parse" | .Fa "struct mparse *parse" | ||
.Fa "int fd" | .Fa "int fd" | ||
|
|
||
.Fa "struct mparse *parse" | .Fa "struct mparse *parse" | ||
.Fa "struct mdoc **mdoc" | .Fa "struct mdoc **mdoc" | ||
.Fa "struct man **man" | .Fa "struct man **man" | ||
.Fa "char **sodest" | |||
.Fc | .Fc | ||
.Ft "const char *" | .Ft "const char *" | ||
.Fo mparse_strerror | .Fo mparse_strerror | ||
|
|
||
.Fo mparse_strlevel | .Fo mparse_strlevel | ||
.Fa "enum mandoclevel" | .Fa "enum mandoclevel" | ||
.Fc | .Fc | ||
.Ft "enum mandoclevel" | |||
.Fo mparse_wait | |||
.Fa "struct mparse *parse" | |||
.Fc | |||
.In sys/types.h | |||
.In mandoc.h | .In mandoc.h | ||
.In mdoc.h | .In mdoc.h | ||
.Ft void | |||
.Fo mdoc_deroff | |||
.Fa "char **dest" | |||
.Fa "const struct mdoc_node *node" | |||
.Fc | |||
.Ft "const struct mdoc_meta *" | .Ft "const struct mdoc_meta *" | ||
.Fo mdoc_meta | .Fo mdoc_meta | ||
.Fa "const struct mdoc *mdoc" | .Fa "const struct mdoc *mdoc" | ||
|
|
||
.Fc | .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; | ||
.In sys/types.h | |||
.In mandoc.h | .In mandoc.h | ||
.In man.h | .In man.h | ||
.Ft void | |||
.Fo man_deroff | |||
.Fa "char **dest" | |||
.Fa "const struct man_node *node" | |||
.Fc | |||
.Ft "const struct man_meta *" | .Ft "const struct man_meta *" | ||
.Fo man_meta | .Fo man_meta | ||
.Fa "const struct man *man" | .Fa "const struct man *man" | ||
|
|
||
.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 | parse files or file descriptors with | ||
|
|
||
.Fn man_node ; | .Fn man_node ; | ||
.It | .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 parse new files. | ||
.El | .El | ||
.Pp | |||
The | |||
.Nm | |||
library also contains routines for translating character strings into glyphs | |||
.Pq see Fn mchars_alloc | |||
and parsing escape sequences from strings | |||
.Pq see Fn mandoc_escape . | |||
.Sh REFERENCE | .Sh REFERENCE | ||
This section documents the functions, types, and variables available | This section documents the functions, types, and variables available | ||
via | via | ||
.In mandoc.h . | .In mandoc.h , | ||
with the exception of those documented in | |||
.Xr mandoc_escape 3 | |||
and | |||
.Xr mchars_alloc 3 . | |||
.Ss Types | .Ss Types | ||
.Bl -ohang | .Bl -ohang | ||
.It Vt "enum mandoc_esc" | |||
An escape sequence classification. | |||
.It Vt "enum mandocerr" | .It Vt "enum mandocerr" | ||
A fatal error, error, or warning message during parsing. | A fatal error, error, or warning message during parsing. | ||
.It Vt "enum mandoclevel" | .It Vt "enum mandoclevel" | ||
|
|
||
.Vt "enum mandocerr" | .Vt "enum mandocerr" | ||
as regards system operation. | as regards system operation. | ||
.It Vt "struct mchars" | .It Vt "struct mchars" | ||
An opaque pointer to an object allowing for translation between | An opaque pointer to a a character table. | ||
character strings and glyphs. | Created with | ||
See | .Xr mchars_alloc 3 | ||
.Fn mchars_alloc . | and freed with | ||
.It Vt "enum mparset" | .Xr mchars_free 3 . | ||
The type of parser when reading input. | |||
This should usually be | |||
.Dv MPARSE_AUTO | |||
for auto-detection. | |||
.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 | ||
|
|
||
.El | .El | ||
.Ss Functions | .Ss Functions | ||
.Bl -ohang | .Bl -ohang | ||
.It Fn mandoc_escape | .It Fn man_deroff | ||
Scan an escape sequence, i.e., a character string beginning with | Obtain a text-only representation of a | ||
.Sq \e . | .Vt struct man_node , | ||
Pass a pointer to the character after the | including text contained in its child nodes. | ||
.Sq \e | To be used on children of the pointer returned from | ||
as | .Fn man_node . | ||
.Va end ; | When it is no longer needed, the pointer returned from | ||
it will be set to the supremum of the parsed escape sequence unless | .Fn man_deroff | ||
returning | can be passed to | ||
.Dv ESCAPE_ERROR , | .Xr free 3 . | ||
in which case the string is bogus and should be | |||
thrown away. | |||
If not | |||
.Dv ESCAPE_ERROR | |||
or | |||
.Dv ESCAPE_IGNORE , | |||
.Va start | |||
is set to the first relevant character of the substring (font, glyph, | |||
whatever) of length | |||
.Va sz . | |||
Both | |||
.Va start | |||
and | |||
.Va sz | |||
may be | |||
.Dv NULL . | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa mandoc.c . | |||
.It Fn man_meta | .It Fn man_meta | ||
Obtain the meta-data of a successful parse. | Obtain the meta-data of a successful | ||
.Xr man 7 | |||
parse. | |||
This may only be used on a pointer returned by | This may only be used on a pointer returned by | ||
.Fn mparse_result . | .Fn mparse_result . | ||
Declared in | Declared in | ||
|
|
||
implemented in | implemented in | ||
.Pa man.c . | .Pa man.c . | ||
.It Fn man_node | .It Fn man_node | ||
Obtain the root node of a successful parse. | Obtain the root node of a successful | ||
.Xr man 7 | |||
parse. | |||
This may only be used on a pointer returned by | 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 mchars_alloc | .It Fn mdoc_deroff | ||
Allocate an | Obtain a text-only representation of a | ||
.Vt "struct mchars *" | .Vt struct mdoc_node , | ||
object for translating special characters into glyphs. | including text contained in its child nodes. | ||
See | To be used on children of the pointer returned from | ||
.Xr mandoc_char 7 | .Fn mdoc_node . | ||
for an overview of special characters. | When it is no longer needed, the pointer returned from | ||
The object must be freed with | .Fn mdoc_deroff | ||
.Fn mchars_free . | can be passed to | ||
Declared in | .Xr free 3 . | ||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mchars_free | |||
Free an object created with | |||
.Fn mchars_alloc . | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mchars_num2char | |||
Convert a character index (e.g., the \eN\(aq\(aq escape) into a | |||
printable ASCII character. | |||
Returns \e0 (the nil character) if the input sequence is malformed. | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mchars_num2uc | |||
Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into | |||
a Unicode codepoint. | |||
Returns \e0 (the nil character) if the input sequence is malformed. | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mchars_spec2cp | |||
Convert a special character into a valid Unicode codepoint. | |||
Returns \-1 on failure or a non-zero Unicode codepoint on success. | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mchars_spec2str | |||
Convert a special character into an ASCII string. | |||
Returns | |||
.Dv NULL | |||
on failure. | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa chars.c . | |||
.It Fn mdoc_meta | .It Fn mdoc_meta | ||
Obtain the meta-data of a successful parse. | Obtain the meta-data of a successful | ||
.Xr mdoc | |||
parse. | |||
This may only be used on a pointer returned by | This may only be used on a pointer returned by | ||
.Fn mparse_result . | .Fn mparse_result . | ||
Declared in | Declared in | ||
|
|
||
implemented in | implemented in | ||
.Pa mdoc.c . | .Pa mdoc.c . | ||
.It Fn mdoc_node | .It Fn mdoc_node | ||
Obtain the root node of a successful parse. | Obtain the root node of a successful | ||
.Xr mdoc | |||
parse. | |||
This may only be used on a pointer returned by | This may only be used on a pointer returned by | ||
.Fn mparse_result . | .Fn mparse_result . | ||
Declared in | Declared in | ||
|
|
||
Allocate a parser. | Allocate a parser. | ||
The arguments have the following effect: | The arguments have the following effect: | ||
.Bl -tag -offset 5n -width inttype | .Bl -tag -offset 5n -width inttype | ||
.It Ar inttype | .It Ar options | ||
When set to | When the | ||
.Dv MPARSE_MDOC | .Dv MPARSE_MDOC | ||
or | or | ||
.Dv MPARSE_MAN , | .Dv MPARSE_MAN | ||
only that parser will be used. | bit is set, only that parser is used. | ||
With | Otherwise, the document type is automatically detected. | ||
.Dv MPARSE_AUTO , | .Pp | ||
the document type will be automatically detected. | When the | ||
.Dv MPARSE_SO | |||
bit is set, | |||
.Xr roff 7 | |||
.Ic \&so | |||
file inclusion requests are always honoured. | |||
Otherwise, if the request is the only content in an input file, | |||
only the file name is remembered, to be returned in the | |||
.Fa sodest | |||
argument of | |||
.Fn mparse_result . | |||
.Pp | |||
When the | |||
.Dv MPARSE_QUICK | |||
bit is set, parsing is aborted after the NAME section. | |||
This is for example useful in | |||
.Xr makewhatis 8 | |||
.Fl Q | |||
to quickly build minimal databases. | |||
.It Ar wlevel | .It Ar wlevel | ||
Can be set to | Can be set to | ||
.Dv MANDOCLEVEL_FATAL , | .Dv MANDOCLEVEL_FATAL , | ||
|
|
||
See | See | ||
.Pa main.c | .Pa main.c | ||
for an example. | for an example. | ||
.It Ar mchars | |||
An opaque pointer to a a character table obtained from | |||
.Xr mchars_alloc 3 . | |||
.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 . | ||
.It Ar quick | |||
When set, parsing is aborted after the NAME section. | |||
This is for example useful to quickly build minimal databases. | |||
.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_open | |||
If the | |||
.Fa fname | |||
ends in | |||
.Pa .gz , | |||
open with | |||
.Xr gunzip 1 ; | |||
otherwise, with | |||
.Xr open 2 . | |||
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 | |||
.Fn mparse_readfd | |||
or used directly. | |||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa read.c . | |||
.It Fn mparse_readfd | .It Fn mparse_readfd | ||
Parse a file or file descriptor. | Parse a file or file descriptor. | ||
If | If | ||
.Va fd | .Va fd | ||
is -1, | is -1, open | ||
.Va fname | .Va fname | ||
is opened for reading. | with | ||
.Fn mparse_open . | |||
Otherwise, | Otherwise, | ||
.Va fname | .Va fname | ||
is assumed to be the name associated with | is assumed to be the name associated with | ||
.Va fd . | .Va fd . | ||
This may be called multiple times with different parameters; however, | Calls | ||
.Fn mparse_wait | |||
before returning. | |||
This function 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 | ||
|
|
||
.Fn mparse_readfd | .Fn mparse_readfd | ||
returned less than MANDOCLEVEL_FATAL | returned less than MANDOCLEVEL_FATAL | ||
.Pc | .Pc | ||
should invoke this function, in which case one of the two pointers will | should invoke this function, in which case one of the three pointers will | ||
be filled in. | be filled in. | ||
Declared in | Declared in | ||
.In mandoc.h , | .In mandoc.h , | ||
|
|
||
.In mandoc.h , | .In mandoc.h , | ||
implemented in | implemented in | ||
.Pa read.c . | .Pa read.c . | ||
.It Fn mparse_wait | |||
Bury a | |||
.Xr gunzip 1 | |||
child process that was spawned with | |||
.Fn mparse_open . | |||
To be called after the parse sequence is complete. | |||
Not needed after | |||
.Fn mparse_readfd , | |||
but does no harm in that case, either. | |||
Returns | |||
.Dv MANDOCLEVEL_OK | |||
on success and | |||
.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 | |||
.In mandoc.h , | |||
implemented in | |||
.Pa read.c . | |||
.El | .El | ||
.Ss Variables | .Ss Variables | ||
.Bl -ohang | .Bl -ohang | ||
|
|
||
A non-breaking space character. | A non-breaking space character. | ||
.It Dv ASCII_HYPH | .It Dv ASCII_HYPH | ||
A soft hyphen. | A soft hyphen. | ||
.It Dv ASCII_BREAK | |||
A breakable zero-width space. | |||
.El | .El | ||
.Pp | .Pp | ||
Escape characters are also passed verbatim into text strings. | Escape characters are also passed verbatim into text strings. | ||
|
|
||
backslash | backslash | ||
.Pq Sq \e . | .Pq Sq \e . | ||
To construct human-readable text, these should be intercepted with | To construct human-readable text, these should be intercepted with | ||
.Fn mandoc_escape | .Xr mandoc_escape 3 | ||
and converted with one of | and converted with one the functions described in | ||
.Fn mchars_num2char , | .Xr mchars_alloc 3 . | ||
.Fn mchars_spec2str , | |||
and so on. | |||
.Ss Man Abstract Syntax Tree | .Ss Man Abstract Syntax Tree | ||
This AST is governed by the ontological rules dictated in | This AST is governed by the ontological rules dictated in | ||
.Xr man 7 | .Xr man 7 | ||
|
|
||
.El | .El | ||
.Pp | .Pp | ||
The only elements capable of nesting other elements are those with | The only elements capable of nesting other elements are those with | ||
next-lint scope as documented in | next-line scope as documented in | ||
.Xr man 7 . | .Xr man 7 . | ||
.Ss Mdoc Abstract Syntax Tree | .Ss Mdoc Abstract Syntax Tree | ||
This AST is governed by the ontological | This AST is governed by the ontological | ||
|
|
||
.Xr mandoc 1 | .Xr mandoc 1 | ||
are unable to render them in any meaningful way. | are 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 mandoc_escape 3 , | |||
.Xr mandoc_malloc 3 , | |||
.Xr mchars_alloc 3 , | |||
.Xr eqn 7 , | .Xr eqn 7 , | ||
.Xr man 7 , | .Xr man 7 , | ||
.Xr mandoc_char 7 , | .Xr mandoc_char 7 , |