-.\" $Id: mandoc.3,v 1.11 2011/06/22 22:10:02 kristaps Exp $
+.\" $Id: mandoc.3,v 1.24 2014/03/23 11:25:26 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: June 22 2011 $
+.Dd $Mdocdate: March 23 2014 $
.Dt MANDOC 3
.Os
.Sh NAME
.Nm mandoc ,
+.Nm mandoc_calloc ,
.Nm mandoc_escape ,
+.Nm mandoc_malloc ,
+.Nm mandoc_realloc ,
+.Nm mandoc_strdup ,
+.Nm mandoc_strndup ,
.Nm man_meta ,
+.Nm man_mparse ,
.Nm man_node ,
.Nm mchars_alloc ,
.Nm mchars_free ,
.Nm mdoc_node ,
.Nm mparse_alloc ,
.Nm mparse_free ,
+.Nm mparse_getkeep ,
+.Nm mparse_keep ,
.Nm mparse_readfd ,
.Nm mparse_reset ,
.Nm mparse_result ,
.Nm mparse_strlevel
.Nd mandoc macro compiler library
.Sh LIBRARY
-.Lb mandoc
+.Lb libmandoc
.Sh SYNOPSIS
-.In man.h
-.In mdoc.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"
.Fo mandoc_escape
-.Fa "const char **in"
-.Fa "const char **seq"
-.Fa "int *len"
-.Fc
-.Ft "const struct man_meta *"
-.Fo man_meta
-.Fa "const struct man *man"
-.Fc
-.Ft "const struct man_node *"
-.Fo man_node
-.Fa "const struct man *man"
+.Fa "const char **end"
+.Fa "const char **start"
+.Fa "int *sz"
.Fc
+.Ft "void *"
+.Fn mandoc_malloc "size_t size"
.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
.Fn mchars_free "struct mchars *p"
.Ft char
.Fn mchars_num2uc "const char *cp" "size_t sz"
.Ft "const char *"
.Fo mchars_spec2str
-.Fa "struct mchars *p"
+.Fa "const struct mchars *p"
.Fa "const char *cp"
.Fa "size_t sz"
.Fa "size_t *rsz"
.Fc
.Ft int
.Fo mchars_spec2cp
-.Fa "struct mchars *p"
+.Fa "const struct mchars *p"
.Fa "const char *cp"
.Fa "size_t sz"
-.Ft "const char *"
-.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
-.Fa "enum mparset type"
+.Fa "enum mparset inttype"
.Fa "enum mandoclevel wlevel"
-.Fa "mandocmsg msg"
-.Fa "void *msgarg"
+.Fa "mandocmsg mmsg"
+.Fa "char *defos"
+.Fa "int quick"
+.Fc
+.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
.Fa "struct mparse *parse"
.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"
.Fo mparse_readfd
.Fa "struct mparse *parse"
.Fo mparse_strlevel
.Fa "enum mandoclevel"
.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_macronames;
-.Fd "#define ASCII_NBRSP"
-.Fd "#define ASCII_HYPH"
+.In mandoc.h
+.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
The
.Nm mandoc
A fatal error, error, or warning message during parsing.
.It Vt "enum mandoclevel"
A classification of an
-.Vt "enum mandoclevel"
+.Vt "enum mandocerr"
as regards system operation.
.It Vt "struct mchars"
An opaque pointer to an object allowing for translation between
.It Vt "enum mparset"
The type of parser when reading input.
This should usually be
-.Va MPARSE_AUTO
+.Dv MPARSE_AUTO
for auto-detection.
.It Vt "struct mparse"
An opaque pointer to a running parse sequence.
.It Fn mandoc_escape
Scan an escape sequence, i.e., a character string beginning with
.Sq \e .
-Pass a pointer to this string as
+Pass a pointer to the character after the
+.Sq \e
+as
.Va end ;
it will be set to the supremum of the parsed escape sequence unless
-returning ESCAPE_ERROR, in which case the string is bogus and should be
+returning
+.Dv ESCAPE_ERROR ,
+in which case the string is bogus and should be
thrown away.
-If not ESCAPE_ERROR or ESCAPE_IGNORE,
+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 start
and
.Va sz
-may be NULL.
+may be
+.Dv NULL .
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa mandoc.c .
.It Fn man_meta
Obtain the meta-data of a successful 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
+Get the parser used for the current output.
+Declared in
+.In man.h ,
+implemented in
+.Pa man.c .
.It Fn man_node
Obtain the root node of a successful 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 mchars_alloc
Allocate an
.Vt "struct mchars *"
for an overview of special characters.
The object must be freed with
.Fn mchars_free .
+Declared in
+.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 NULL on failure.
+Returns
+.Dv NULL
+on failure.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa chars.c .
.It Fn mdoc_meta
Obtain the meta-data of a successful 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 mdoc_node
Obtain the root node of a successful 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
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
.Fn mparse_reset
is called between parses.
.Fn mparse_free
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
Free all memory allocated by
.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
Parse a file or file descriptor.
If
This may be called multiple times with different parameters; however,
.Fn mparse_reset
should be invoked between parses.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
.It Fn mparse_reset
Reset a parser so that
.Fn mparse_readfd
may be used again.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
.It Fn mparse_result
Obtain the result of a parse.
Only successful parses
.Pc
should invoke this function, in which case one of the two pointers will
be filled in.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
.It Fn mparse_strerror
Return a statically-allocated string representation of an error code.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
.It Fn mparse_strlevel
Return a statically-allocated string representation of a level code.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
.El
.Ss Variables
.Bl -ohang
The
.Nm
library was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff