=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.17 retrieving revision 1.31 diff -u -p -r1.17 -r1.31 --- mandoc/Attic/mdoc.3 2009/03/14 05:21:58 1.17 +++ mandoc/Attic/mdoc.3 2009/07/05 19:30:49 1.31 @@ -1,23 +1,21 @@ -.\" $Id: mdoc.3,v 1.17 2009/03/14 05:21:58 kristaps Exp $ +.\" $Id: mdoc.3,v 1.31 2009/07/05 19:30:49 kristaps Exp $ .\" .\" Copyright (c) 2009 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 copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 14 2009 $ -.Dt mdoc 3 +.Dd $Mdocdate: July 5 2009 $ +.Dt MDOC 3 .Os .\" SECTION .Sh NAME @@ -26,7 +24,8 @@ .Nm mdoc_endparse , .Nm mdoc_node , .Nm mdoc_meta , -.Nm mdoc_free +.Nm mdoc_free , +.Nm mdoc_reset .Nd mdoc macro compiler library .\" SECTION .Sh SYNOPSIS @@ -34,15 +33,17 @@ .Vt extern const char * const * mdoc_macronames; .Vt extern const char * const * mdoc_argnames; .Ft "struct mdoc *" -.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb" +.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb" +.Ft int +.Fn mdoc_reset "struct mdoc *mdoc" .Ft void .Fn mdoc_free "struct mdoc *mdoc" .Ft int .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf" .Ft "const struct mdoc_node *" -.Fn mdoc_node "struct mdoc *mdoc" +.Fn mdoc_node "const struct mdoc *mdoc" .Ft "const struct mdoc_meta *" -.Fn mdoc_meta "struct mdoc *mdoc" +.Fn mdoc_meta "const struct mdoc *mdoc" .Ft int .Fn mdoc_endparse "struct mdoc *mdoc" .\" SECTION @@ -53,14 +54,7 @@ library parses lines of .Xr mdoc 7 input (and .Em only -mdoc) into an abstract syntax tree that generalises the semantic -annotation of its input. Common front-ends for -.Nm -are -.Xr mdocterm 1 , -.Xr mdoclint 1 -and -.Xr mdoctree 1 . +mdoc) into an abstract syntax tree (AST). .\" PARAGRAPH .Pp In general, applications initiate a parsing sequence with @@ -75,7 +69,10 @@ and .Fn mdoc_meta , then free all allocated memory with .Fn mdoc_free . -See the +The +.Fn mdoc_reset +function may be used in order to reset the parser for another input +sequence. See the .Sx EXAMPLES section for a full example. .\" PARAGRAPH @@ -123,10 +120,20 @@ Allocates a parsing structure. The .Fa data pointer is passed to callbacks in .Fa cb , -which are documented further in the header file. Returns NULL on -failure. If non-NULL, the pointer must be freed with +which are documented further in the header file. +The +.Fa pflags +arguments are defined in +.Pa mdoc.h . +Returns NULL on failure. If non-NULL, the pointer must be freed with .Fn mdoc_free . .\" LIST-ITEM +.It Fn mdoc_reset +Reset the parser for another parse routine. After its use, +.Fn mdoc_parseln +behaves as if invoked for the first time. If it returns 0, memory could +not be allocated. +.\" LIST-ITEM .It Fn mdoc_free Free all resources of a parser. The pointer is no longer valid after invocation. @@ -182,7 +189,10 @@ or after .Fn mdoc_endparse or .Fn mdoc_parseln -fail, it may be incomplete. This AST is governed by the ontological +fail, it may be incomplete. +.\" PARAGRAPH +.Pp +This AST is governed by the ontological rules dictated in .Xr mdoc 7 and derives its terminology accordingly. @@ -209,9 +219,7 @@ fields), its position in the tree (the .Va next and .Va prev -fields) and type-specific data (the -.Va data -field). +fields) and some type-specific data. .\" PARAGRAPH .Pp The tree itself is arranged according to the following normal form, @@ -257,13 +265,13 @@ will truncate the file's last character (see Further, this example does not error-check nor free memory upon failure. .Bd -literal -offset "XXXX" struct mdoc *mdoc; -struct mdoc_node *node; +const struct mdoc_node *node; char *buf; size_t len; int line; line = 1; -mdoc = mdoc_alloc(NULL, NULL); +mdoc = mdoc_alloc(NULL, 0, NULL); while ((buf = fgetln(fp, &len))) { buf[len - 1] = '\\0'; @@ -282,9 +290,7 @@ mdoc_free(mdoc); .Ed .\" SECTION .Sh SEE ALSO -.Xr mdocterm 1 , -.Xr mdoclint 1 , -.Xr mdoctree 1 , +.Xr mandoc 1 , .Xr mdoc 7 .\" SECTION .Sh AUTHORS @@ -298,15 +304,41 @@ utility was written by .\" LIST-ITEM .It The -.Sq \&Xc +.Sq \&.Xc and -.Sq \&Xo +.Sq \&.Xo macros aren't handled when used to span lines for the -.Sq \&It +.Sq \&.It macro. .\" LIST-ITEM .It The -.Sq \&Bsx -macro doesn't yet understand version arguments. +.Sq \&.Bsx +macro family doesn't yet understand version arguments. +.\" LIST-ITEM +.It +If not given a value, the \-offset argument to +.Sq \&.Bd +and +.Sq \&.Bl +should be the width of +.Qq ; +instead, a value of +.Li 10n +is provided. +.\" LIST-ITEM +.It +Columns widths in +.Sq \&.Bl \-column +should default to width +.Qq +if not included. +.\" LIST-ITEM +.It +List-width suffix +.Qq m +isn't handled. +.\" LIST-ITEM +.It +Contents of the SYNOPSIS section aren't checked. .El