=================================================================== RCS file: /cvs/mandoc/Attic/man.3,v retrieving revision 1.11 retrieving revision 1.14 diff -u -p -r1.11 -r1.14 --- mandoc/Attic/man.3 2010/01/07 19:10:09 1.11 +++ mandoc/Attic/man.3 2010/03/30 19:20:33 1.14 @@ -1,6 +1,6 @@ -.\" $Id: man.3,v 1.11 2010/01/07 19:10:09 kristaps Exp $ +.\" $Id: man.3,v 1.14 2010/03/30 19:20:33 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009-2010 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -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: January 7 2010 $ +.Dd $Mdocdate: March 30 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,82 @@ 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 +.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 @@ -84,24 +162,25 @@ and available to programmers. Following that, the .Sx Abstract Syntax Tree section documents the output tree. -.\" SUBSECTION +. +. .Ss Types Both functions (see .Sx Functions ) and variables (see .Sx Variables ) may use the following types: -.Bl -ohang -offset "XXXX" -.\" LIST-ITEM +.Bl -ohang +. .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 +188,12 @@ See .Sx Abstract Syntax Tree for details. .El -.\" SUBSECTION +. +. .Ss Functions Function descriptions follow: -.Bl -ohang -offset "XXXX" -.\" LIST-ITEM +.Bl -ohang +. .It Fn man_alloc Allocates a parsing structure. The .Fa data @@ -126,29 +206,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 +243,17 @@ or .Fn man_endparse return 0, the data will be incomplete. .El -.\" SUBSECTION +. +. .Ss Variables The following variables are also defined: -.Bl -ohang -offset "XXXX" -.\" LIST-ITEM +.Bl -ohang +. .It Va man_macronames An array of string-ified token names. .El -.\" SUBSECTION +. +. .Ss Abstract Syntax Tree The .Nm @@ -185,13 +267,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 +292,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 -offset "XXXX" -.\" LIST-ITEM +.Bl -tag -width "ELEMENTXX" -compact .It ROOT \(<- mnode+ .It mnode @@ -232,21 +313,19 @@ 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 .Fn parsed . -Note that, if the last line of the file isn't newline-terminated, this -will truncate the file's last character (see -.Xr fgetln 3 ) . -Further, this example does not error-check nor free memory upon failure. -.Bd -literal -offset "XXXX" +This example does not error-check nor free memory upon failure. +.Bd -literal -offset indent struct man *man; struct man_node *node; char *buf; @@ -255,29 +334,36 @@ int line; line = 1; man = man_alloc(NULL, 0, NULL); +buf = NULL; +alloc_len = 0; -while ((buf = fgetln(fp, &len))) { - buf[len - 1] = '\e0'; - if ( ! man_parseln(man, line, buf)) - errx(1, "man_parseln"); - line++; +while ((len = getline(&buf, &alloc_len, stdin)) >= 0) { + if (len && buflen[len - 1] = '\en') + buf[len - 1] = '\e0'; + if ( ! man_parseln(man, line, buf)) + errx(1, "man_parseln"); + line++; } +free(buf); + if ( ! man_endparse(man)) - errx(1, "man_endparse"); + errx(1, "man_endparse"); if (NULL == (node = man_node(man))) - errx(1, "man_node"); + errx(1, "man_node"); parsed(man, node); man_free(man); .Ed -.\" SECTION +. +. .Sh SEE ALSO .Xr mandoc 1 , .Xr man 7 -.\" SECTION +. +. .Sh AUTHORS The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . +.An Kristaps Dzonsons Aq kristaps@bsd.lv .