version 1.12, 2011/07/11 08:43:27 |
version 1.24, 2014/03/23 11:25:26 |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm mandoc , |
.Nm mandoc , |
|
.Nm mandoc_calloc , |
.Nm mandoc_escape , |
.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_node , |
.Nm man_node , |
.Nm mchars_alloc , |
.Nm mchars_alloc , |
.Nm mchars_free , |
.Nm mchars_free , |
|
|
.Nm mdoc_node , |
.Nm mdoc_node , |
.Nm mparse_alloc , |
.Nm mparse_alloc , |
.Nm mparse_free , |
.Nm mparse_free , |
|
.Nm mparse_getkeep , |
|
.Nm mparse_keep , |
.Nm mparse_readfd , |
.Nm mparse_readfd , |
.Nm mparse_reset , |
.Nm mparse_reset , |
.Nm mparse_result , |
.Nm mparse_result , |
|
|
.Nm mparse_strlevel |
.Nm mparse_strlevel |
.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 mdoc.h |
|
.In mandoc.h |
.In mandoc.h |
|
.Fd "#define ASCII_NBRSP" |
|
.Fd "#define ASCII_HYPH" |
|
.Fd "#define ASCII_BREAK" |
|
.Ft "void *" |
|
.Fo mandoc_calloc |
|
.Fa "size_t nmemb" |
|
.Fa "size_t size" |
|
.Fc |
.Ft "enum mandoc_esc" |
.Ft "enum mandoc_esc" |
.Fo mandoc_escape |
.Fo mandoc_escape |
.Fa "const char **in" |
.Fa "const char **end" |
.Fa "const char **seq" |
.Fa "const char **start" |
.Fa "int *len" |
.Fa "int *sz" |
.Fc |
.Fc |
.Ft "const struct man_meta *" |
.Ft "void *" |
.Fo man_meta |
.Fn mandoc_malloc "size_t size" |
.Fa "const struct man *man" |
|
.Fc |
|
.Ft "const struct man_node *" |
|
.Fo man_node |
|
.Fa "const struct man *man" |
|
.Fc |
|
.Ft "struct mchars *" |
.Ft "struct mchars *" |
.Fn mchars_alloc |
.Fo mandoc_realloc |
|
.Fa "void *ptr" |
|
.Fa "size_t size" |
|
.Fc |
|
.Ft "char *" |
|
.Fn mandoc_strdup |
|
.Fn mchars_alloc "void" |
.Ft void |
.Ft void |
.Fn mchars_free "struct mchars *p" |
.Fn mchars_free "struct mchars *p" |
.Ft char |
.Ft char |
|
|
.Fn mchars_num2uc "const char *cp" "size_t sz" |
.Fn mchars_num2uc "const char *cp" "size_t sz" |
.Ft "const char *" |
.Ft "const char *" |
.Fo mchars_spec2str |
.Fo mchars_spec2str |
.Fa "struct mchars *p" |
.Fa "const struct mchars *p" |
.Fa "const char *cp" |
.Fa "const char *cp" |
.Fa "size_t sz" |
.Fa "size_t sz" |
.Fa "size_t *rsz" |
.Fa "size_t *rsz" |
.Fc |
.Fc |
.Ft int |
.Ft int |
.Fo mchars_spec2cp |
.Fo mchars_spec2cp |
.Fa "struct mchars *p" |
.Fa "const struct mchars *p" |
.Fa "const char *cp" |
.Fa "const char *cp" |
.Fa "size_t sz" |
.Fa "size_t sz" |
.Ft "const char *" |
|
.Fc |
.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 |
.Ft void |
.Fo mparse_alloc |
.Fo mparse_alloc |
.Fa "enum mparset type" |
.Fa "enum mparset inttype" |
.Fa "enum mandoclevel wlevel" |
.Fa "enum mandoclevel wlevel" |
.Fa "mandocmsg msg" |
.Fa "mandocmsg mmsg" |
.Fa "void *msgarg" |
.Fa "char *defos" |
|
.Fa "int quick" |
.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 const char * |
|
.Fo mparse_getkeep |
|
.Fa "const struct mparse *parse" |
|
.Fc |
|
.Ft void |
|
.Fo mparse_keep |
|
.Fa "struct mparse *parse" |
|
.Fc |
.Ft "enum mandoclevel" |
.Ft "enum mandoclevel" |
.Fo mparse_readfd |
.Fo mparse_readfd |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
|
|
.Fo mparse_strlevel |
.Fo mparse_strlevel |
.Fa "enum mandoclevel" |
.Fa "enum mandoclevel" |
.Fc |
.Fc |
.Vt extern const char * const * man_macronames; |
.In mandoc.h |
|
.In mdoc.h |
|
.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 mandoc.h |
.Fd "#define ASCII_HYPH" |
.In man.h |
|
.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 189 An escape sequence classification. |
|
Line 234 An escape sequence classification. |
|
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 an object allowing for translation between |
Line 219 messages emitted by the parser. |
|
Line 264 messages emitted by the parser. |
|
.It Fn mandoc_escape |
.It Fn mandoc_escape |
Scan an escape sequence, i.e., a character string beginning with |
Scan an escape sequence, i.e., a character string beginning with |
.Sq \e . |
.Sq \e . |
Pass a pointer to this string as |
Pass a pointer to the character after the |
|
.Sq \e |
|
as |
.Va end ; |
.Va end ; |
it will be set to the supremum of the parsed escape sequence unless |
it will be set to the supremum of the parsed escape sequence unless |
returning |
returning |
|
|
.Va sz |
.Va sz |
may be |
may be |
.Dv NULL . |
.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 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 |
|
.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 |
.It Fn man_node |
Obtain the root node of a successful parse. |
Obtain the root node of a successful 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 |
|
.In man.h , |
|
implemented in |
|
.Pa man.c . |
.It Fn mchars_alloc |
.It Fn mchars_alloc |
Allocate an |
Allocate an |
.Vt "struct mchars *" |
.Vt "struct mchars *" |
|
|
for an overview of special characters. |
for an overview of special characters. |
The object must be freed with |
The object must be freed with |
.Fn mchars_free . |
.Fn mchars_free . |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa chars.c . |
.It Fn mchars_free |
.It Fn mchars_free |
Free an object created with |
Free an object created with |
.Fn mchars_alloc . |
.Fn mchars_alloc . |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa chars.c . |
.It Fn mchars_num2char |
.It Fn mchars_num2char |
Convert a character index (e.g., the \eN\(aq\(aq escape) into a |
Convert a character index (e.g., the \eN\(aq\(aq escape) into a |
printable ASCII character. |
printable ASCII character. |
Returns \e0 (the nil character) if the input sequence is malformed. |
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 |
.It Fn mchars_num2uc |
Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into |
Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into |
a Unicode codepoint. |
a Unicode codepoint. |
Returns \e0 (the nil character) if the input sequence is malformed. |
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 |
.It Fn mchars_spec2cp |
Convert a special character into a valid Unicode codepoint. |
Convert a special character into a valid Unicode codepoint. |
Returns \-1 on failure or a non-zero Unicode codepoint on success. |
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 |
.It Fn mchars_spec2str |
Convert a special character into an ASCII string. |
Convert a special character into an ASCII string. |
Returns |
Returns |
.Dv NULL |
.Dv NULL |
on failure. |
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 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 |
|
.In mdoc.h , |
|
implemented in |
|
.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 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 |
|
.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: |
|
.Bl -tag -offset 5n -width inttype |
|
.It Ar inttype |
|
When set to |
|
.Dv MPARSE_MDOC |
|
or |
|
.Dv MPARSE_MAN , |
|
only that parser will be used. |
|
With |
|
.Dv MPARSE_AUTO , |
|
the document type will be automatically detected. |
|
.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 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 . |
|
.It Ar quick |
|
When set, parsing is aborted after the NAME section. |
|
This is for example useful to quickly build minimal databases. |
|
.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. |
.Fn mparse_free |
.Fn mparse_free |
must be called to free the memory allocated by this function. |
must be called to free the memory allocated by this function. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
.It Fn mparse_free |
.It Fn mparse_free |
Free all memory allocated by |
Free all memory allocated by |
.Fn mparse_alloc . |
.Fn mparse_alloc . |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
|
.It Fn mparse_getkeep |
|
Acquire the keep buffer. |
|
Must follow a call of |
|
.Fn mparse_keep . |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.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_readfd |
.It Fn mparse_readfd |
Parse a file or file descriptor. |
Parse a file or file descriptor. |
If |
If |
Line 308 is assumed to be the name associated with |
|
Line 466 is assumed to be the name associated with |
|
This may be called multiple times with different parameters; however, |
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 |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
.It Fn mparse_reset |
.It Fn mparse_reset |
Reset a parser so that |
Reset a parser so that |
.Fn mparse_readfd |
.Fn mparse_readfd |
may be used again. |
may be used again. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.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 |
Only successful parses |
Line 322 returned less than MANDOCLEVEL_FATAL |
|
Line 488 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 two pointers will |
be filled in. |
be filled in. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
.It Fn mparse_strerror |
.It Fn mparse_strerror |
Return a statically-allocated string representation of an error code. |
Return a statically-allocated string representation of an error code. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
.It Fn mparse_strlevel |
.It Fn mparse_strlevel |
Return a statically-allocated string representation of a level code. |
Return a statically-allocated string representation of a level code. |
|
Declared in |
|
.In mandoc.h , |
|
implemented in |
|
.Pa read.c . |
.El |
.El |
.Ss Variables |
.Ss Variables |
.Bl -ohang |
.Bl -ohang |
Line 568 levels of badly-nested blocks. |
|
Line 746 levels of badly-nested blocks. |
|
The |
The |
.Nm |
.Nm |
library was written by |
library was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |