=================================================================== RCS file: /cvs/mandoc/Attic/man.3,v retrieving revision 1.12 retrieving revision 1.13 diff -u -p -r1.12 -r1.13 --- mandoc/Attic/man.3 2010/02/17 19:22:01 1.12 +++ mandoc/Attic/man.3 2010/03/27 10:04:56 1.13 @@ -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 .\" @@ -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 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