version 1.21, 2013/10/05 20:30:05 |
version 1.29, 2014/11/26 23:42:14 |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm mandoc , |
.Nm mandoc , |
.Nm mandoc_escape , |
.Nm man_deroff , |
.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 mandoc |
.Lb libmandoc |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In man.h |
.In sys/types.h |
.In mdoc.h |
|
.In mandoc.h |
.In mandoc.h |
.Ft "enum mandoc_esc" |
.Fd "#define ASCII_NBRSP" |
.Fo mandoc_escape |
.Fd "#define ASCII_HYPH" |
.Fa "const char const **end" |
.Fd "#define ASCII_BREAK" |
.Fa "const char const **start" |
.Ft struct mparse * |
.Fa "int *sz" |
|
.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 |
|
.Ft "struct mchars *" |
|
.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 "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" |
|
.Fc |
|
.Ft void |
|
.Fo mparse_alloc |
.Fo mparse_alloc |
.Fa "enum mparset type" |
.Fa "int options" |
.Fa "enum mandoclevel wlevel" |
.Fa "enum mandoclevel wlevel" |
.Fa "mandocmsg msg" |
.Fa "mandocmsg mmsg" |
.Fa "void *msgarg" |
.Fa "const struct mchars *mchars" |
|
.Fa "char *defos" |
.Fc |
.Fc |
.Ft void |
.Ft void |
|
.Fo (*mandocmsg) |
|
.Fa "enum mandocerr errtype" |
|
.Fa "enum mandoclevel level" |
|
.Fa "const char *file" |
|
.Fa "int line" |
|
.Fa "int col" |
|
.Fa "const char *msg" |
|
.Fc |
|
.Ft void |
.Fo mparse_free |
.Fo mparse_free |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fc |
.Fc |
.Ft void |
.Ft const char * |
.Fo mparse_getkeep |
.Fo mparse_getkeep |
.Fa "const struct mparse *parse" |
.Fa "const struct mparse *parse" |
.Fc |
.Fc |
|
|
.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 |
.Vt extern const char * const * man_macronames; |
.Ft "enum mandoclevel" |
|
.Fo mparse_wait |
|
.Fa "struct mparse *parse" |
|
.Fc |
|
.In sys/types.h |
|
.In mandoc.h |
|
.In mdoc.h |
|
.Ft void |
|
.Fo mdoc_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" |
|
.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; |
.Fd "#define ASCII_NBRSP" |
.In sys/types.h |
.Fd "#define ASCII_HYPH" |
.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 |
|
.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 |
Line 165 The following describes a general parse sequence: |
|
Line 172 The following describes a general parse sequence: |
|
.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" |
A classification of an |
A classification of an |
.Vt "enum mandoclevel" |
.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 |
Line 230 messages emitted by the parser. |
|
Line 232 messages emitted by the parser. |
|
.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 |
|
|
.Pa mdoc.c . |
.Pa mdoc.c . |
.It Fn mparse_alloc |
.It Fn mparse_alloc |
Allocate a parser. |
Allocate a parser. |
|
The arguments have the following effect: |
|
.Bl -tag -offset 5n -width inttype |
|
.It Ar options |
|
When the |
|
.Dv MPARSE_MDOC |
|
or |
|
.Dv MPARSE_MAN |
|
bit is set, only that parser is used. |
|
Otherwise, the document type is automatically detected. |
|
.Pp |
|
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 |
|
Can be set to |
|
.Dv MANDOCLEVEL_FATAL , |
|
.Dv MANDOCLEVEL_ERROR , |
|
or |
|
.Dv MANDOCLEVEL_WARNING . |
|
Messages below the selected level will be suppressed. |
|
.It Ar mmsg |
|
A callback function to handle errors and warnings. |
|
See |
|
.Pa main.c |
|
for an example. |
|
.It Ar mchars |
|
An opaque pointer to a a character table obtained from |
|
.Xr mchars_alloc 3 . |
|
.It Ar defos |
|
A default string for the |
|
.Xr mdoc 7 |
|
.Sq \&Os |
|
macro, overriding the |
|
.Dv OSNAME |
|
preprocessor definition and the results of |
|
.Xr uname 3 . |
|
.El |
|
.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 |
.Fn mparse_reset |
.Fn mparse_reset |
is called between parses. |
is called between parses. |
|
|
.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 |
Line 419 i.e., those where |
|
Line 450 i.e., those where |
|
.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 |
Line 473 The following non-printing characters may be embedded |
|
Line 526 The following non-printing characters may be embedded |
|
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. |
Line 480 An escape character is a sequence of characters beginn |
|
Line 535 An escape character is a sequence of characters beginn |
|
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 |
Line 529 where capitalised non-terminals represent nodes. |
|
Line 582 where capitalised non-terminals represent nodes. |
|
.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 , |