=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.2 retrieving revision 1.14 diff -u -p -r1.2 -r1.14 --- mandoc/Attic/mdoc.3 2009/01/16 15:58:50 1.2 +++ mandoc/Attic/mdoc.3 2009/03/12 15:55:11 1.14 @@ -1,18 +1,38 @@ +.\" $Id: mdoc.3,v 1.14 2009/03/12 15:55:11 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 16 2009 $ +.Dd $Mdocdate: March 12 2009 $ .Dt mdoc 3 .Os -.\" +.\" SECTION .Sh NAME .Nm mdoc_alloc , .Nm mdoc_parseln , .Nm mdoc_endparse , -.Nm mdoc_result , +.Nm mdoc_node , +.Nm mdoc_meta , .Nm mdoc_free .Nd mdoc macro compiler library -.\" +.\" SECTION .Sh SYNOPSIS -.In mdoc.h +.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" .Ft void @@ -20,14 +40,36 @@ .Ft int .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf" .Ft "const struct mdoc_node *" -.Fn mdoc_result "struct mdoc *mdoc" +.Fn mdoc_node "struct mdoc *mdoc" +.Ft "const struct mdoc_meta *" +.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 mdoc input into an abstract syntax tree. +.Dq mdoc , +which is used to format BSD manual pages, is a macro package of the +.Dq roff +language. The +.Nm +library implements only those macros documented in the +.Xr mdoc 7 +and +.Xr mdoc.samples 7 +manuals. Documents with +.Xr refer 1 , +.Xr eqn 1 +and other pre-processor sections aren't accomodated. +.\" PARAGRAPH +.Pp +.Nm +is +.Ud +.\" PARAGRAPH +.Pp In general, applications initiate a parsing sequence with .Fn mdoc_alloc , parse each line in a document with @@ -35,15 +77,56 @@ parse each line in a document with close the parsing session with .Fn mdoc_endparse , operate over the syntax tree returned by -.Fn mdoc_result , +.Fn mdoc_node +and +.Fn mdoc_meta , then free all allocated memory with .Fn mdoc_free . See the .Sx EXAMPLES section for a full example. +.\" PARAGRAPH .Pp +This section further defines the +.Sx Types , +.Sx Functions +and +.Sx Variables +available to programmers. Following that, +.Sx Character Encoding +describes input format. Lastly, +.Sx Abstract Syntax Tree , +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 @@ -52,32 +135,197 @@ pointer is passed to callbacks in which are documented further in the header file. Returns NULL on failure. If non-NULL, the pointer must be freed with .Fn mdoc_free . +.\" 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_result , +.Fn mdoc_node , the resulting tree is incomplete. Returns 0 on failure, 1 on success. -.It Fn mdoc_result -Returns the result of the parse or NULL on failure. Note that if +.\" LIST-ITEM +.It Fn mdoc_node +Returns the first node of the parse. Note that if .Fn mdoc_parseln or .Fn mdoc_endparse return 0, the tree will be incomplete. +.It Fn mdoc_meta +Returns the document's parsed meta-data. If this information has not +yet been supplied or +.Fn mdoc_parseln +or +.Fn mdoc_endparse +return 0, the data will be incomplete. .El +.\" SUBSECTION +.Ss Variables +The following variables are also defined: +.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 +.\" SUBSECTION +.Ss Character Encoding +The +.Xr mdoc 3 +library accepts only printable ASCII characters as defined by +.Xr isprint 3 . +Non-ASCII character sequences are delimited in various ways. All are +preceeded by an escape character +.Sq \\ +and followed by either an open-parenthesis +.Sq \&( +for two-character sequences; an open-bracket +.Sq \&[ +for n-character sequences (terminated at a close-bracket +.Sq \&] ) ; +an asterisk and open-parenthesis +.Sq \&*( +for two-character sequences; +an asterisk and non-open-parenthesis +.Sq \&* +for single-character sequences; or one of a small set of standalone +single characters for other escapes. +.\" PARAGRAPH .Pp +Examples: +.Pp +.Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact +.\" LIST-ITEM +.It \\*(<= +prints +.Dq \*(<= +.Pq greater-equal +.\" LIST-ITEM +.It \\(<- +prints +.Dq \(<- +.Pq left-arrow +.\" LIST-ITEM +.It \\[<-] +also prints +.Dq \(<- +.Pq left-arrow +.\" LIST-ITEM +.It \\*(Ba +prints +.Dq \*(Ba +.Pq bar +.\" LIST-ITEM +.It \\*q +prints +.Dq \*q +.Pq double-quote +.El +.\" PARAGRAPH +.Pp +All escaped sequences are syntax-checked, but it's up to the front-end +system to correctly render them to the output device. +.\" SUBSECTION +.Ss Abstract Syntax Tree +The .Nm -is -.Ud -.\" +functions produce an abstract syntax tree (AST) describing the input +lines 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 +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 type-specific data (the +.Va data +field). +.\" 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. +.\" PARAGRAPH +.Pp +The rule-of-thumb for mapping node types to macros follows. In-line +elements, such as +.Sq \&.Em foo , +are classified as ELEMENT nodes, which can only contain text. +Multi-line elements, such as +.Sq \&.Sh , +are BLOCK elements, where the HEAD constitutes line contents and the +BODY constitutes subsequent lines. In-line elements with matching +pairs, such as +.Sq \&.So +and +.Sq \&.Sc , +are BLOCK elements with no HEAD tag. The only exception to this is +.Sq \&.Eo +and +.Sq \&.Ec , +which has a HEAD and TAIL node corresponding to the enclosure string. +TEXT nodes, obviously, constitute text, and the ROOT node is the +document's root. +.\" SECTION .Sh EXAMPLES The following example reads lines from stdin and parses them, operating on the finished parse tree with @@ -86,7 +334,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; @@ -105,28 +353,62 @@ while ((buf = fgetln(fp, &len))) { if ( ! mdoc_endparse(mdoc)) errx(1, "mdoc_endparse"); -if (NULL == (node = mdoc_result(mdoc))) - errx(1, "mdoc_result"); +if (NULL == (node = mdoc_node(mdoc))) + errx(1, "mdoc_node"); parsed(mdoc, node); mdoc_free(mdoc); .Ed -.\" +.\" SECTION +.Sh COMPATIBILITY +In general, only those macros specified by +.Xr mdoc.samples 7 +and +.Xr mdoc 7 +for +.Ox +and +.Nx +are supported; support for other +.Bx +systems is in progress. +.Bl -bullet +.\" LIST-ITEM +.It +NetBSD +.Sq \&It \-nested +is assumed for all lists: any list may be nested and +.Sq \-enum +lists will restart the sequence only for the sub-list. +.\" LIST-ITEM +.It +Newer NetBSD-style +.Sq \&It \-column +syntax, where column widths may be preceeded by other arguments (instead +of proceeded), is not supported. +.\" LIST-ITEM +.It +The +.Sq \&At +macro only accepts a single parameter. +.El +.\" SECTION .Sh SEE ALSO .Xr mdoc 7 , .Xr mdoc.samples 7 , .Xr groff 1 , .Xr mdocml 1 -.\" -.\" +.\" SECTION .Sh AUTHORS The .Nm utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . -.\" -.\" -.Sh BUGS +.\" SECTION +.Sh CAVEATS +.Bl -bullet +.\" LIST-ITEM +.It The .Sq \&Xc and @@ -135,9 +417,4 @@ 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 -When -.Sq \&It \-column -is invoked, whitespace is not stripped around -.Sq \&Ta -or tab-character separators. +.El