More use default tags, this time I and U. Also fix a stack overflow

[mandoc.git] / man.3

diff --git a/man.3 b/man.3
index 3191a11eeba988e40aaf631cb82e1c2149803d43..826c6bdad5b9485b22d9673ec4a645d8cf1b6227 100644 (file)
--- a/man.3
+++ b/man.3
@@ -1,4 +1,4 @@
-.\"    $Id: man.3,v 1.19 2010/06/26 15:36:37 kristaps Exp $
+.\"    $Id: man.3,v 1.27 2010/12/17 11:41:45 kristaps Exp $

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


@@ -14,7 +14,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: June 26 2010 $
+.Dd $Mdocdate: December 17 2010 $

 .Dt MAN 3
 .Os
 .Sh NAME
 .Dt MAN 3
 .Os
 .Sh NAME


@@ -29,11 +29,14 @@
 .Nd man macro compiler library
 .Sh SYNOPSIS
 .In mandoc.h
 .Nd man macro compiler library
 .Sh SYNOPSIS
 .In mandoc.h

-.In regs.h

 .In man.h
 .Vt extern const char * const * man_macronames;
 .Ft "struct man *"
 .In man.h
 .Vt extern const char * const * man_macronames;
 .Ft "struct man *"

-.Fn man_alloc "void *data" "int pflags" "mandocmsg msgs"
+.Fo man_alloc
+.Fa "struct regset *regs"
+.Fa "void *data"
+.Fa "mandocmsg msgs"
+.Fc

 .Ft int
 .Fn man_endparse "struct man *man"
 .Ft void
 .Ft int
 .Fn man_endparse "struct man *man"
 .Ft void


@@ -45,7 +48,6 @@
 .Ft int
 .Fo man_parseln
 .Fa "struct man *man"
 .Ft int
 .Fo man_parseln
 .Fa "struct man *man"

-.Fa "const struct regset *regs"

 .Fa "int line"
 .Fa "char *buf"
 .Fc
 .Fa "int line"
 .Fa "char *buf"
 .Fc


@@ -74,95 +76,30 @@ The
 .Fn man_reset
 function may be used in order to reset the parser for another input
 sequence.
 .Fn man_reset
 function may be used in order to reset the parser for another input
 sequence.

-See the
-.Sx EXAMPLES
-section for a full example.

 .Pp
 Beyond the full set of macros defined in
 .Xr man 7 ,
 the
 .Nm
 .Pp
 Beyond the full set of macros defined in
 .Xr man 7 ,
 the
 .Nm

-library also accepts the following macros:
+library also accepts the following macro:

 .Pp
 .Bl -tag -width Ds -compact
 .It PD
 .Pp
 .Bl -tag -width Ds -compact
 .It PD

-Has no effect.  Handled as a current-scope line macro.
-.It Sp
-A synonym for
-.Sq sp 0.5v
-.Pq part of the standard preamble for Perl documentation .
-Handled as a line macro.
-.It Vb
-A synonym for
-.Sq nf
-.Pq part of the standard preamble for Perl documentation .
-Handled as a current-scope line macro.
-.It Ve
-A synonym for
-.Sq fi ,
-closing
-.Sq Vb
-.Pq part of the standard preamble for Perl documentation .
+Has no effect.

 Handled as a current-scope line macro.
 .El
 Handled as a current-scope line macro.
 .El

-.Pp
-Furthermore, the following escapes are accepted to allow
-.Xr pod2man 1
-documents to be correctly formatted:
-\e*(-- (dash),
-\e*(PI (pi),
-\e*(L" (left double-quote),
-\e*(R" (right double-quote),
-\e*(C+ (C++),
-\e*(C` (left single-quote),
-\e*(C' (right single-quote),
-\e*(Aq (apostrophe),
-\e*^ (hat),
-\e*, (comma),
-\e*~ (tilde),
-\e*/ (forward slash),
-\e*: (umlaut),
-\e*8 (beta),
-\e*o (degree),
-\e*(D- (Eth),
-\e*(d- (eth),
-\e*(Th (Thorn),
-and
-\e*(th (thorn).
-.Sh REFERENCE
-This section further defines the
-.Sx Types ,
-.Sx Functions
-and
-.Sx Variables
-available to programmers.
-Following that, the
-.Sx Abstract Syntax Tree
-section documents the output tree.

 .Ss Types
 .Ss Types

-Both functions (see
-.Sx Functions )
-and variables (see
-.Sx Variables )
-may use the following types:

 .Bl -ohang
 .It Vt struct man
 .Bl -ohang
 .It Vt struct man

-An opaque type defined in
-.Pa man.c .
+An opaque type.

 Its values are only used privately within the library.
 Its values are only used privately within the library.

-.It Vt mandocmsg
-A function callback type defined in
-.Pa mandoc.h .

 .It Vt struct man_node
 A parsed node.
 .It Vt struct man_node
 A parsed node.

-Defined in
-.Pa man.h .

 See
 .Sx Abstract Syntax Tree
 for details.
 .El
 .Ss Functions
 See
 .Sx Abstract Syntax Tree
 for details.
 .El
 .Ss Functions

-Function descriptions follow:

 .Bl -ohang
 .It Fn man_alloc
 Allocates a parsing structure.
 .Bl -ohang
 .It Fn man_alloc
 Allocates a parsing structure.


@@ -170,10 +107,6 @@ The
 .Fa data
 pointer is passed to
 .Fa msgs .
 .Fa data
 pointer is passed to
 .Fa msgs .

-The
-.Fa pflags
-arguments are defined in
-.Pa man.h .

 Returns NULL on failure.
 If non-NULL, the pointer must be freed with
 .Fn man_free .
 Returns NULL on failure.
 If non-NULL, the pointer must be freed with
 .Fn man_free .


@@ -287,14 +220,16 @@ on the finished parse tree with
 .Fn parsed .
 This example does not error-check nor free memory upon failure.
 .Bd -literal -offset indent
 .Fn parsed .
 This example does not error-check nor free memory upon failure.
 .Bd -literal -offset indent

+struct regset regs;

 struct man *man;
 struct man_node *node;
 char *buf;
 size_t len;
 int line;
 
 struct man *man;
 struct man_node *node;
 char *buf;
 size_t len;
 int line;
 

+bzero(&regs, sizeof(struct regset));

 line = 1;
 line = 1;

-man = man_alloc(NULL, 0, NULL);
+man = man_alloc(&regs, NULL, NULL);

 buf = NULL;
 alloc_len = 0;
 
 buf = NULL;
 alloc_len = 0;
 


@@ -317,9 +252,13 @@ parsed(man, node);
 man_free(man);
 .Ed
 .Pp
 man_free(man);
 .Ed
 .Pp

-Please see
+To compile this, execute
+.Pp
+.Dl % cc main.c libman.a libmandoc.a
+.Pp
+where

 .Pa main.c
 .Pa main.c

-in the source archive for a rigorous reference.
+is the example file.

 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr man 7
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr man 7