improve SQL style: avoid "SELECT *", be explicit in what columns we want;

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 4d0b20d6507e6e02f64e945c18fd5910a46dbb97..2e6b78b96a3f9eb5e146ee2be6ee4ed1ef31f420 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.17 2012/01/13 15:27:14 joerg 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>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,12 +15,17 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: January 13 2012 $
+.Dd $Mdocdate: March 23 2014 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Dt MANDOC 3
 .Os
 .Sh NAME
 .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_mparse ,
 .Nm man_node ,
 .Nm man_meta ,
 .Nm man_mparse ,
 .Nm man_node ,


@@ -43,31 +48,33 @@
 .Nm mparse_strlevel
 .Nd mandoc macro compiler library
 .Sh LIBRARY
 .Nm mparse_strlevel
 .Nd mandoc macro compiler 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"
 .Fo mandoc_escape
 .Fa "const char **end"
 .Fa "const char **start"
 .Fa "int *sz"
 .Fc
 .Ft "enum mandoc_esc"
 .Fo mandoc_escape
 .Fa "const char **end"
 .Fa "const char **start"
 .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 "void *"
+.Fn mandoc_malloc "size_t size"

 .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
 .Fn mchars_free "struct mchars *p"
 .Ft char
 .Ft void
 .Fn mchars_free "struct mchars *p"
 .Ft char


@@ -86,28 +93,29 @@
 .Fa "const struct mchars *p"
 .Fa "const char *cp"
 .Fa "size_t sz"
 .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
 .Fc
 .Ft void
 .Fo mparse_alloc

-.Fa "enum mparset type"
+.Fa "enum mparset inttype"

 .Fa "enum mandoclevel wlevel"
 .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
 .Fc
 .Ft void
 .Fo mparse_free
 .Fa "struct mparse *parse"
 .Fc

-.Ft void
+.Ft const char *

 .Fo mparse_getkeep
 .Fa "const struct mparse *parse"
 .Fc
 .Fo mparse_getkeep
 .Fa "const struct mparse *parse"
 .Fc


@@ -139,11 +147,33 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
 .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;
 .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
 .Sh DESCRIPTION
 The
 .Nm mandoc


@@ -204,7 +234,7 @@ An escape sequence classification.
 A fatal error, error, or warning message during parsing.
 .It Vt "enum mandoclevel"
 A classification of an
 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
 as regards system operation.
 .It Vt "struct mchars"
 An opaque pointer to an object allowing for translation between


@@ -257,16 +287,32 @@ and
 .Va sz
 may be
 .Dv NULL .
 .Va sz
 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 .
 .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.
 .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 .
 .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 *"
 .It Fn mchars_alloc
 Allocate an
 .Vt "struct mchars *"


@@ -276,52 +322,136 @@ See
 for an overview of special characters.
 The object must be freed with
 .Fn mchars_free .
 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 .
 .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.
 .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.
 .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.
 .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.
 .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
 Obtain the meta-data of a successful parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 .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 .
 .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.
 .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.
 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 .
 .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 .
 .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.
 .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
 .It Fn mparse_readfd
 Parse a file or file descriptor.
 If


@@ -336,10 +466,18 @@ is assumed to be the name associated with
 This may be called multiple times with different parameters; however,
 .Fn mparse_reset
 should be invoked between parses.
 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.
 .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
 .It Fn mparse_result
 Obtain the result of a parse.
 Only successful parses


@@ -350,10 +488,22 @@ returned less than MANDOCLEVEL_FATAL
 .Pc
 should invoke this function, in which case one of the two pointers will
 be filled in.
 .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.
 .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.
 .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
 .El
 .Ss Variables
 .Bl -ohang


@@ -596,5 +746,4 @@ levels of badly-nested blocks.
 The
 .Nm
 library was written by
 The
 .Nm
 library was written by

-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .