Give man(7) section and subsection headers hanging indentation.

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 2ee6eae181d3ebcb39409dcdece29be7e8f27c40..a41e25b934d0ec4d6d933e48ef46795ea0f7cf3e 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,7 +1,7 @@
-.\"    $Id: mandoc.3,v 1.26 2014/09/03 23:21:47 schwarze Exp $
+.\"    $Id: mandoc.3,v 1.31 2015/01/15 04:26:40 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>

-.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -15,7 +15,7 @@
 .\" 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: September 3 2014 $
+.Dd $Mdocdate: January 15 2015 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Dt MANDOC 3
 .Os
 .Sh NAME


@@ -39,11 +39,10 @@
 .Nm mparse_strlevel
 .Nm mparse_wait ,
 .Nd mandoc macro compiler library
 .Nm mparse_strlevel
 .Nm mparse_wait ,
 .Nd mandoc macro compiler library

-.Sh LIBRARY
-.Lb libmandoc

 .Sh SYNOPSIS
 .In sys/types.h
 .In mandoc.h
 .Sh SYNOPSIS
 .In sys/types.h
 .In mandoc.h

+.Pp

 .Fd "#define ASCII_NBRSP"
 .Fd "#define ASCII_HYPH"
 .Fd "#define ASCII_BREAK"
 .Fd "#define ASCII_NBRSP"
 .Fd "#define ASCII_HYPH"
 .Fd "#define ASCII_BREAK"


@@ -52,6 +51,7 @@
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"

+.Fa "const struct mchars *mchars"

 .Fa "char *defos"
 .Fc
 .Ft void
 .Fa "char *defos"
 .Fc
 .Ft void


@@ -80,7 +80,6 @@
 .Fa "struct mparse *parse"
 .Fa "int *fd"
 .Fa "const char *fname"
 .Fa "struct mparse *parse"
 .Fa "int *fd"
 .Fa "const char *fname"

-.Fa "pid_t *child_pid"

 .Fc
 .Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fc
 .Ft "enum mandoclevel"
 .Fo mparse_readfd


@@ -110,7 +109,6 @@
 .Ft "enum mandoclevel"
 .Fo mparse_wait
 .Fa "struct mparse *parse"
 .Ft "enum mandoclevel"
 .Fo mparse_wait
 .Fa "struct mparse *parse"

-.Fa "pid_t child_pid"

 .Fc
 .In sys/types.h
 .In mandoc.h
 .Fc
 .In sys/types.h
 .In mandoc.h


@@ -173,12 +171,19 @@ The following describes a general parse sequence:
 .Bl -enum
 .It
 initiate a parsing sequence with
 .Bl -enum
 .It
 initiate a parsing sequence with

+.Xr mchars_alloc 3
+and

 .Fn mparse_alloc ;
 .It
 .Fn mparse_alloc ;
 .It

-parse files or file descriptors with
+open a file with
+.Xr open 2
+or
+.Fn mparse_open ;
+.It
+parse it with

 .Fn mparse_readfd ;
 .It
 .Fn mparse_readfd ;
 .It

-retrieve a parsed syntax tree, if the parse was successful, with
+retrieve the syntax tree with

 .Fn mparse_result ;
 .It
 iterate over parse nodes with
 .Fn mparse_result ;
 .It
 iterate over parse nodes with


@@ -187,7 +192,9 @@ or
 .Fn man_node ;
 .It
 free all allocated memory with
 .Fn man_node ;
 .It
 free all allocated memory with

-.Fn mparse_free ,
+.Fn mparse_free
+and
+.Xr mchars_free 3 ,

 or invoke
 .Fn mparse_reset
 and parse new files.
 or invoke
 .Fn mparse_reset
 and parse new files.


@@ -203,11 +210,17 @@ and
 .Ss Types
 .Bl -ohang
 .It Vt "enum mandocerr"
 .Ss Types
 .Bl -ohang
 .It Vt "enum mandocerr"

-A fatal error, error, or warning message during parsing.
+An error or warning message during parsing.

 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.

+.It Vt "struct mchars"
+An opaque pointer to a a character table.
+Created with
+.Xr mchars_alloc 3
+and freed with
+.Xr mchars_free 3 .

 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with


@@ -218,7 +231,7 @@ This may be used across parsed input if
 .Fn mparse_reset
 is called between parses.
 .It Vt "mandocmsg"
 .Fn mparse_reset
 is called between parses.
 .It Vt "mandocmsg"

-A prototype for a function to handle fatal error, error, and warning
+A prototype for a function to handle error and warning

 messages emitted by the parser.
 .El
 .Ss Functions
 messages emitted by the parser.
 .El
 .Ss Functions


@@ -322,7 +335,7 @@ This is for example useful in
 to quickly build minimal databases.
 .It Ar wlevel
 Can be set to
 to quickly build minimal databases.
 .It Ar wlevel
 Can be set to

-.Dv MANDOCLEVEL_FATAL ,
+.Dv MANDOCLEVEL_BADARG ,

 .Dv MANDOCLEVEL_ERROR ,
 or
 .Dv MANDOCLEVEL_WARNING .
 .Dv MANDOCLEVEL_ERROR ,
 or
 .Dv MANDOCLEVEL_WARNING .


@@ -332,6 +345,9 @@ A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.
 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
 .It Ar defos
 A default string for the
 .Xr mdoc 7


@@ -384,36 +400,33 @@ open with
 .Xr gunzip 1 ;
 otherwise, with
 .Xr open 2 .
 .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.
 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.

-If applicable, return the
-.Xr gunzip 1
-child process ID in
-.Fa child_pid ,
-or otherwise 0.
-If non-zero, it should be passed to
-.Fn mparse_wait
-after completing the parse sequence.

 Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
 .It Fn mparse_readfd
 Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
 .It Fn mparse_readfd

-Parse a file or file descriptor.
-If
-.Va fd
-is -1,
-.Va fname
-is opened for reading.
-Otherwise,
-.Va fname
-is assumed to be the name associated with
-.Va fd .
-This may be called multiple times with different parameters; however,
+Parse a file descriptor opened with
+.Xr open 2
+or
+.Fn mparse_open .
+Pass the associated filename in
+.Va fname .
+Calls
+.Fn mparse_wait
+before returning.
+This function may be called multiple times with different parameters; however,

 .Fn mparse_reset
 should be invoked between parses.
 Declared in
 .Fn mparse_reset
 should be invoked between parses.
 Declared in


@@ -430,14 +443,7 @@ implemented in
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.

-Only successful parses
-.Po
-i.e., those where
-.Fn mparse_readfd
-returned less than MANDOCLEVEL_FATAL
-.Pc
-should invoke this function, in which case one of the three pointers will
-be filled in.
+One of the three pointers will be filled in.

 Declared in
 .In mandoc.h ,
 implemented in
 Declared in
 .In mandoc.h ,
 implemented in


@@ -457,11 +463,12 @@ implemented in
 .It Fn mparse_wait
 Bury a
 .Xr gunzip 1
 .It Fn mparse_wait
 Bury a
 .Xr gunzip 1

-child process
-.Fa child_pid
-that was spawned with
+child process that was spawned with

 .Fn mparse_open .
 To be called after the parse sequence is complete.
 .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
 Returns
 .Dv MANDOCLEVEL_OK
 on success and