=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.8 retrieving revision 1.18 diff -u -p -r1.8 -r1.18 --- mandoc/Attic/mdoc.3 2009/02/23 12:45:19 1.8 +++ mandoc/Attic/mdoc.3 2009/03/16 22:19:19 1.18 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.3,v 1.8 2009/02/23 12:45:19 kristaps Exp $ +.\" $Id: mdoc.3,v 1.18 2009/03/16 22:19:19 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: February 23 2009 $ +.Dd $Mdocdate: March 16 2009 $ .Dt mdoc 3 .Os .\" SECTION @@ -49,24 +49,20 @@ .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 +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 mdoc.samples 7 -manuals. +.Xr mdoctree 1 . .\" 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 @@ -89,9 +85,9 @@ This section further defines the .Sx Functions and .Sx Variables -available to programmers. The last sub-section, -.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 @@ -99,7 +95,7 @@ Both functions (see and variables (see .Sx Variables ) may use the following types: -.Bl -ohang +.Bl -ohang -offset "XXXX" .\" LIST-ITEM .It Vt struct mdoc An opaque type defined in @@ -120,7 +116,7 @@ for details. .\" SUBSECTION .Ss Functions Function descriptions follow: -.Bl -ohang +.Bl -ohang -offset "XXXX" .\" LIST-ITEM .It Fn mdoc_alloc Allocates a parsing structure. The @@ -165,7 +161,7 @@ return 0, the data will be incomplete. .\" SUBSECTION .Ss Variables The following variables are also defined: -.Bl -ohang +.Bl -ohang -offset "XXXX" .\" LIST-ITEM .It Va mdoc_macronames An array of string-ified token names. @@ -177,8 +173,8 @@ An array of string-ified token argument names. .Ss Abstract Syntax Tree 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 , @@ -186,9 +182,20 @@ or after .Fn mdoc_endparse or .Fn mdoc_parseln -fail, it may be incomplete. +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 @@ -213,7 +220,7 @@ field). The tree itself is arranged according to the following normal form, where capitalised non-terminals represent nodes. .Pp -.Bl -tag -width "ELEMENTXX" -compact +.Bl -tag -width "ELEMENTXX" -compact -offset "XXXX" .\" LIST-ITEM .It ROOT \(<- mnode+ @@ -242,27 +249,6 @@ although a TEXT node will generally have a non-zero-le 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 @@ -272,7 +258,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; @@ -299,10 +285,10 @@ mdoc_free(mdoc); .Ed .\" SECTION .Sh SEE ALSO -.Xr mdoc 7 , -.Xr mdoc.samples 7 , -.Xr groff 1 , -.Xr mdocml 1 +.Xr mdocterm 1 , +.Xr mdoclint 1 , +.Xr mdoctree 1 , +.Xr mdoc 7 .\" SECTION .Sh AUTHORS The @@ -310,45 +296,20 @@ The utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION -.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 +.Sh CAVEATS +.Bl -dash -compact +.\" LIST-ITEM +.It +The .Sq \&Xc and .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. -.Pp -Incompatible: only those macros specified by -.Xr mdoc.samples 7 -and -.Xr mdoc 7 -for -.Ox -are supported; support for -.Nx -and other -.Bx -systems is in progress. +macro. +.\" LIST-ITEM +.It +The +.Sq \&Bsx +macro doesn't yet understand version arguments. +.El