=================================================================== RCS file: /cvs/mandoc/Attic/mdoc.3,v retrieving revision 1.8 retrieving revision 1.16 diff -u -p -r1.8 -r1.16 --- mandoc/Attic/mdoc.3 2009/02/23 12:45:19 1.8 +++ mandoc/Attic/mdoc.3 2009/03/12 23:05:21 1.16 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.3,v 1.8 2009/02/23 12:45:19 kristaps Exp $ +.\" $Id: mdoc.3,v 1.16 2009/03/12 23:05:21 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 12 2009 $ .Dt mdoc 3 .Os .\" SECTION @@ -59,7 +59,10 @@ library implements only those macros documented in the .Xr mdoc 7 and .Xr mdoc.samples 7 -manuals. +manuals. Documents with +.Xr refer 1 , +.Xr eqn 1 +and other pre-processor sections aren't accomodated. .\" PARAGRAPH .Pp .Nm @@ -89,7 +92,9 @@ This section further defines the .Sx Functions and .Sx Variables -available to programmers. The last sub-section, +available to programmers. Following that, +.Sx Character Encoding +describes input format. Lastly, .Sx Abstract Syntax Tree , documents the output tree. .\" SUBSECTION @@ -99,7 +104,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 +125,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 +170,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. @@ -174,6 +179,63 @@ 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 .Nm @@ -213,7 +275,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+ @@ -272,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; @@ -298,6 +360,62 @@ 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 +.Sq \&Cd +isn't labelled as callable but is. +.\" 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. +.\" LIST-ITEM +.It +Some manuals use +.Sq \&Li +incorrectly by following it with a delimeter (see +.Xr mdoc.samples 7 ) +and expecting the delimiter to render. This is not supported. +.\" LIST-ITEM +.It +The system-name macros ( +.Ns Sq \&At , +.Sq \&Bsx , +.Sq \&Bx , +.Sq \&Fx , +.Sq \&Nx , +.Sq \&Ox , +and +.Sq \&Ux ) +are callable. +.El +.\" SECTION .Sh SEE ALSO .Xr mdoc 7 , .Xr mdoc.samples 7 , @@ -310,16 +428,11 @@ 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 -bullet +.\" LIST-ITEM +.It +The .Sq \&Xc and .Sq \&Xo @@ -327,28 +440,10 @@ 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. +.\" LIST-ITEM +.It +The +.Sq \&Bsx +macro doesn't understand yet the arguments as dictated for +.Nx . +.El