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 fe6503d5477ef050ef9c371f4be86b7b0dc2b9d7..2e6b78b96a3f9eb5e146ee2be6ee4ed1ef31f420 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.22 2013/10/06 17:01:52 schwarze 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: October 6 2013 $
+.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 ,


@@ -45,28 +50,30 @@
 .Sh LIBRARY
 .Lb libmandoc
 .Sh SYNOPSIS
 .Sh LIBRARY
 .Lb libmandoc
 .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
 .Ft "enum mandoc_esc"
 .Fo mandoc_escape

-.Fa "const char const **end"
-.Fa "const char const **start"
+.Fa "const char **end"
+.Fa "const char **start"

 .Fa "int *sz"
 .Fc
 .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 *"

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


@@ -87,26 +94,28 @@
 .Fa "const char *cp"
 .Fa "size_t sz"
 .Fc
 .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
 .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


@@ -138,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


@@ -203,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


@@ -352,6 +383,42 @@ implemented in
 .Pa mdoc.c .
 .It Fn mparse_alloc
 Allocate a parser.
 .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.
 The same parser may be used for multiple files so long as
 .Fn mparse_reset
 is called between parses.