Fixed re-adjustment of scope in exiting roff instructions (libman).

Added title-case check for (libman).
Fixed premature closure of roff instruction scope (libman).
Added documentation of ignored roff macros to man(3).

1 files changed, 90 insertions, 30 deletions

diff --git a/man.3 b/man.3
index 174e85b5..552be651 100644
--- a/man.3
+++ b/man.3
@@ -1,4 +1,4 @@
-.\"	$Id: man.3,v 1.12 2010/02/17 19:22:01 kristaps Exp $
+.\"	$Id: man.3,v 1.13 2010/03/27 10:04:56 kristaps Exp $
 .\"
 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,11 +14,13 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: February 17 2010 $
+.Dd $Mdocdate: March 27 2010 $
 .Dt MAN 3
 .Os
-.\" SECTION
+.
+.
 .Sh NAME
+.Nm man ,
 .Nm man_alloc ,
 .Nm man_parseln ,
 .Nm man_endparse ,
@@ -27,7 +29,8 @@
 .Nm man_free ,
 .Nm man_reset
 .Nd man macro compiler library
-.\" SECTION
+.
+.
 .Sh SYNOPSIS
 .In man.h
 .Vt extern const char * const * man_macronames;
@@ -45,16 +48,17 @@
 .Fn man_meta "const struct man *man"
 .Ft int
 .Fn man_endparse "struct man *man"
-.\" SECTION
+.
+.
 .Sh DESCRIPTION
 The
-.Nm man
+.Nm
 library parses lines of
 .Xr man 7
 input (and
 .Em only
 man) into an abstract syntax tree (AST).
-.\" PARAGRAPH
+.
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn man_alloc ,
@@ -74,8 +78,58 @@ function may be used in order to reset the parser for another input
 sequence.  See the
 .Sx EXAMPLES
 section for a full example.
-.\" PARAGRAPH
+.
+.Pp
+Beyond the full set of macros defined in
+.Xr man 7 ,
+the
+.Nm
+library also accepts the following macros:
+.
 .Pp
+.Bl -tag -width Ds -compact
+.It am
+.It ami
+.It de
+.It dei
+.It ig
+Instructional macros in the original roff language.  Blocks begun by
+these macros end with
+.Sq ..
+and may begin anywhere, although they may not break the next-line
+scoping rules specified in
+.Xr man 7 .
+These blocks are discarded.
+.
+.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 UC
+Has no effect.  Handled as a current-scope 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 .
+Handled as a current-scope line macro.
+.El
+.
+.
+.Sh REFERENCE
 This section further defines the
 .Sx Types ,
 .Sx Functions
@@ -84,7 +138,8 @@ and
 available to programmers.  Following that, the
 .Sx Abstract Syntax Tree
 section documents the output tree.
-.\" SUBSECTION
+.
+.
 .Ss Types
 Both functions (see
 .Sx Functions )
@@ -92,16 +147,16 @@ and variables (see
 .Sx Variables )
 may use the following types:
 .Bl -ohang
-.\" LIST-ITEM
+.
 .It Vt struct man
 An opaque type defined in
 .Pa man.c .
 Its values are only used privately within the library.
-.\" LIST-ITEM
+.
 .It Vt struct man_cb
 A set of message callbacks defined in
 .Pa man.h .
-.\" LIST-ITEM
+.
 .It Vt struct man_node
 A parsed node.  Defined in
 .Pa man.h .
@@ -109,11 +164,12 @@ See
 .Sx Abstract Syntax Tree
 for details.
 .El
-.\" SUBSECTION
+.
+.
 .Ss Functions
 Function descriptions follow:
 .Bl -ohang
-.\" LIST-ITEM
+.
 .It Fn man_alloc
 Allocates a parsing structure.  The
 .Fa data
@@ -126,29 +182,29 @@ arguments are defined in
 .Pa man.h .
 Returns NULL on failure.  If non-NULL, the pointer must be freed with
 .Fn man_free .
-.\" LIST-ITEM
+.
 .It Fn man_reset
 Reset the parser for another parse routine.  After its use,
 .Fn man_parseln
 behaves as if invoked for the first time.
-.\" LIST-ITEM
+.
 .It Fn man_free
 Free all resources of a parser.  The pointer is no longer valid after
 invocation.
-.\" LIST-ITEM
+.
 .It Fn man_parseln
 Parse a nil-terminated line of input.  This line should not contain the
 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 .Fa buf
 is modified by this function.
-.\" LIST-ITEM
+.
 .It Fn man_endparse
 Signals that the parse is complete.  Note that if
 .Fn man_endparse
 is called subsequent to
 .Fn man_node ,
 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
-.\" LIST-ITEM
+.
 .It Fn man_node
 Returns the first node of the parse.  Note that if
 .Fn man_parseln
@@ -163,15 +219,17 @@ or
 .Fn man_endparse
 return 0, the data will be incomplete.
 .El
-.\" SUBSECTION
+.
+.
 .Ss Variables
 The following variables are also defined:
 .Bl -ohang
-.\" LIST-ITEM
+.
 .It Va man_macronames
 An array of string-ified token names.
 .El
-.\" SUBSECTION
+.
+.
 .Ss Abstract Syntax Tree
 The
 .Nm
@@ -185,13 +243,13 @@ or after
 or
 .Fn man_parseln
 fail, it may be incomplete.
-.\" PARAGRAPH
+.
 .Pp
 This AST is governed by the ontological
 rules dictated in
 .Xr man 7
 and derives its terminology accordingly.
-.\" PARAGRAPH
+.
 .Pp
 The AST is composed of
 .Vt struct man_node
@@ -210,13 +268,12 @@ fields), its position in the tree (the
 and
 .Va prev
 fields) and some type-specific data.
-.\" PARAGRAPH
+.
 .Pp
 The tree itself is arranged according to the following normal form,
 where capitalised non-terminals represent nodes.
 .Pp
 .Bl -tag -width "ELEMENTXX" -compact
-.\" LIST-ITEM
 .It ROOT
 \(<- mnode+
 .It mnode
@@ -232,12 +289,13 @@ where capitalised non-terminals represent nodes.
 .It TEXT
 \(<- [[:alpha:]]*
 .El
-.\" PARAGRAPH
+.
 .Pp
 The only elements capable of nesting other elements are those with
 next-lint scope as documented in
 .Xr man 7 .
-.\" SECTION
+.
+.
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
 on the finished parse tree with
@@ -273,11 +331,13 @@ if (NULL == (node = man_node(man)))
 parsed(man, node);
 man_free(man);
 .Ed
-.\" SECTION
+.
+.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr man 7
-.\" SECTION
+.
+.
 .Sh AUTHORS
 The
 .Nm