=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.14 retrieving revision 1.36 diff -u -p -r1.14 -r1.36 --- mandoc/Attic/mdoc.3 2009/03/12 15:55:11 1.14 +++ mandoc/Attic/mdoc.3 2010/01/07 19:10:09 1.36 @@ -1,23 +1,21 @@ -.\" $Id: mdoc.3,v 1.14 2009/03/12 15:55:11 kristaps Exp $ +.\" $Id: mdoc.3,v 1.36 2010/01/07 19:10:09 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. -.\" -.Dd $Mdocdate: March 12 2009 $ -.Dt mdoc 3 +.\" 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 7 2010 $ +.Dt MDOC 3 .Os .\" SECTION .Sh NAME @@ -26,77 +24,67 @@ .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 +.In mdoc.h .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 .Sh DESCRIPTION The .Nm mdoc -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 +library parses lines of .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. +input (and +.Em only +mdoc) into an abstract syntax tree (AST). .\" 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 +parse each line in a document with .Fn mdoc_parseln , close the parsing session with .Fn mdoc_endparse , operate over the syntax tree returned by -.Fn mdoc_node +.Fn mdoc_node 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 -This section further defines the +This section further defines the .Sx Types , -.Sx Functions +.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. +available to programmers. Following that, the +.Sx Abstract Syntax Tree +section documents the output tree. .\" SUBSECTION .Ss Types Both functions (see @@ -118,7 +106,7 @@ A set of message callbacks defined in .It Vt struct mdoc_node A parsed node. Defined in .Pa mdoc.h . -See +See .Sx Abstract Syntax Tree for details. .El @@ -131,37 +119,47 @@ Function descriptions follow: 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 +.Fa cb , +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 +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 +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 +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 +yet been supplied or .Fn mdoc_parseln or .Fn mdoc_endparse @@ -179,79 +177,33 @@ An array of string-ified token names. 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 +The .Nm -functions produce an abstract syntax tree (AST) describing the input -lines in a regular form. It may be reviewed at any time with +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 +.Fn mdoc_endparse or .Fn mdoc_parseln fail, it may be incomplete. .\" PARAGRAPH .Pp -The AST is composed of +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 @@ -264,12 +216,10 @@ and fields), its position in the tree (the .Va parent , .Va child , -.Va next +.Va next and -.Va prev -fields) and type-specific data (the -.Va data -field). +.Va prev +fields) and some type-specific data. .\" PARAGRAPH .Pp The tree itself is arranged according to the following normal form, @@ -301,51 +251,30 @@ where capitalised non-terminals represent nodes. 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 +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 +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 +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" 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'; + buf[len - 1] = '\e0'; if ( ! mdoc_parseln(mdoc, line, buf)) errx(1, "mdoc_parseln"); line++; @@ -360,61 +289,48 @@ parsed(mdoc, node); mdoc_free(mdoc); .Ed .\" SECTION -.Sh COMPATIBILITY -In general, only those macros specified by -.Xr mdoc.samples 7 -and +.Sh SEE ALSO +.Xr mandoc 1 , .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 +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS -.Bl -bullet +.Bl -dash -compact .\" LIST-ITEM .It -The -.Sq \&Xc +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 . +.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. .El