=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.4 retrieving revision 1.30 diff -u -p -r1.4 -r1.30 --- mandoc/Attic/mdoc.3 2009/01/19 17:51:33 1.4 +++ mandoc/Attic/mdoc.3 2009/06/11 07:26:35 1.30 @@ -1,23 +1,41 @@ +.\" $Id: mdoc.3,v 1.30 2009/06/11 07:26:35 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. +.\" +.\" 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: January 19 2009 $ -.Dt mdoc 3 +.Dd $Mdocdate: June 11 2009 $ +.Dt MDOC 3 .Os -.\" +.\" SECTION .Sh NAME .Nm mdoc_alloc , .Nm mdoc_parseln , .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 .Fd #include .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 @@ -28,11 +46,17 @@ .Fn mdoc_meta "struct mdoc *mdoc" .Ft int .Fn mdoc_endparse "struct mdoc *mdoc" -.\" +.\" SECTION .Sh DESCRIPTION The .Nm mdoc -library parses lines of mdoc-macro text into an abstract syntax tree. +library parses lines of +.Xr mdoc 7 +input (and +.Em only +mdoc) into an abstract syntax tree (AST). +.\" PARAGRAPH +.Pp In general, applications initiate a parsing sequence with .Fn mdoc_alloc , parse each line in a document with @@ -45,35 +69,88 @@ 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 .Pp -.\" Function descriptions. +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. +.\" SUBSECTION +.Ss Types +Both functions (see +.Sx Functions ) +and variables (see +.Sx Variables ) +may use the following types: +.Bl -ohang -offset "XXXX" +.\" LIST-ITEM +.It Vt struct mdoc +An opaque type defined in +.Pa mdoc.c . +Its values are only used privately within the library. +.\" LIST-ITEM +.It Vt struct mdoc_cb +A set of message callbacks defined in +.Pa mdoc.h . +.\" LIST-ITEM +.It Vt struct mdoc_node +A parsed node. Defined in +.Pa mdoc.h . +See +.Sx Abstract Syntax Tree +for details. +.El +.\" SUBSECTION +.Ss Functions Function descriptions follow: -.Bl -ohang -offset indent +.Bl -ohang -offset "XXXX" +.\" LIST-ITEM .It Fn mdoc_alloc 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. +.\" LIST-ITEM .It Fn mdoc_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 mdoc_endparse Signals that the parse is complete. Note that if .Fn mdoc_endparse is called subsequent to .Fn mdoc_node , the resulting tree is incomplete. Returns 0 on failure, 1 on success. +.\" LIST-ITEM .It Fn mdoc_node Returns the first node of the parse. Note that if .Fn mdoc_parseln @@ -88,20 +165,96 @@ or .Fn mdoc_endparse return 0, the data will be incomplete. .El -.Pp -.\" Variable descriptions. +.\" SUBSECTION +.Ss Variables The following variables are also defined: -.Bl -ohang -offset indent +.Bl -ohang -offset "XXXX" +.\" LIST-ITEM .It Va mdoc_macronames An array of string-ified token names. +.\" LIST-ITEM .It Va mdoc_argnames An array of string-ified token argument names. .El -.Pp +.\" SUBSECTION +.Ss Abstract Syntax Tree +The .Nm -is -.Ud -.\" +functions produce an abstract syntax tree (AST) describing input in a +regular form. It may be reviewed at any time with +.Fn mdoc_nodes ; +however, if called before +.Fn mdoc_endparse , +or after +.Fn mdoc_endparse +or +.Fn mdoc_parseln +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. +.Qq In-line +elements described in +.Xr mdoc 7 +are described simply as +.Qq elements . +.\" PARAGRAPH +.Pp +The AST is composed of +.Vt struct mdoc_node +nodes with block, head, body, element, root and text types as declared +by the +.Va type +field. Each node also provides its parse point (the +.Va line , +.Va sec , +and +.Va pos +fields), its position in the tree (the +.Va parent , +.Va child , +.Va next +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 +.It ROOT +\(<- mnode+ +.It mnode +\(<- BLOCK | ELEMENT | TEXT +.It BLOCK +\(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]] +.It BLOCK +\(<- BODY [TEXT] [TAIL [TEXT]] +.It ELEMENT +\(<- TEXT* +.It HEAD +\(<- mnode+ +.It BODY +\(<- mnode+ +.It TAIL +\(<- mnode+ +.It TEXT +\(<- [[:alpha:]]* +.El +.\" PARAGRAPH +.Pp +Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of +the BLOCK production. These refer to punctuation marks. Furthermore, +although a TEXT node will generally have a non-zero-length string, in +the specific case of +.Sq \&.Bd \-literal , +an empty line will produce a zero-length string. +.\" SECTION .Sh EXAMPLES The following example reads lines from stdin and parses them, operating on the finished parse tree with @@ -110,7 +263,7 @@ Note that, if the last line of the file isn't newline- 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 +.Bd -literal -offset "XXXX" struct mdoc *mdoc; struct mdoc_node *node; char *buf; @@ -118,7 +271,7 @@ 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'; @@ -135,48 +288,57 @@ if (NULL == (node = mdoc_node(mdoc))) parsed(mdoc, node); mdoc_free(mdoc); .Ed -.\" +.\" SECTION .Sh SEE ALSO -.Xr mdoc 7 , -.Xr mdoc.samples 7 , -.Xr groff 1 , -.Xr mdocml 1 -.\" -.\" +.Xr mandoc 1 , +.Xr mdoc 7 +.\" SECTION .Sh AUTHORS The .Nm utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . -.\" -.\" -.Sh BUGS -Bugs, un-implemented macros and incompabilities are documented in this -section. The baseline for determining whether macro parsing is -.Qq incompatible -is the default -.Xr groff 1 -system bundled with -.Ox . -.Pp -Un-implemented: the -.Sq \&Xc +.\" SECTION +.Sh CAVEATS +.Bl -dash -compact +.\" LIST-ITEM +.It +The +.Sq \&.Xc and -.Sq \&Xo +.Sq \&.Xo macros aren't handled when used to span lines for the -.Sq \&It -macro. Such usage is specifically discouraged in -.Xr mdoc.samples 7 . -.Pp -Bugs: when -.Sq \&It \-column -is invoked, whitespace is not stripped around -.Sq \&Ta -or tab-character separators. -.Pp -Incompatible: the -.Sq \&At -macro only accepts a single parameter. Furthermore, several macros -.Pf ( Sq \&Pp , -.Sq \&It , -and possibly others) accept multiple arguments with a warning. +.Sq \&.It +macro. +.\" LIST-ITEM +.It +The +.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