=================================================================== RCS file: /cvs/mandoc/Attic/mdocml.1,v retrieving revision 1.16 retrieving revision 1.29 diff -u -p -r1.16 -r1.29 --- mandoc/Attic/mdocml.1 2008/12/03 19:21:58 1.16 +++ mandoc/Attic/mdocml.1 2009/01/20 13:44:05 1.29 @@ -1,110 +1,96 @@ .\" -.Dd $Mdocdate: December 3 2008 $ +.Dd $Mdocdate: January 20 2009 $ .Dt mdocml 1 .Os .\" .Sh NAME .Nm mdocml -.Nd compile manpage source into mark-up language +.Nd mdoc macro compiler .\" .Sh SYNOPSIS .Nm mdocml -.Op Fl W -.Op Fl f Ar filter -.Op Fl o Ar outfile +.Op Fl v +.Op Fl W Ns Ar err... .Op Ar infile .\" .Sh DESCRIPTION The .Nm -utility parses mdoc formatted manual source and passes results into an -output filter. The only current output filter is -.Ar xml , -the default. The arguments are as follows: -.Bl -tag -width "\-o outfile" -.It Fl f Ar filter -The output filter name. -.It Fl o Ar outfile -Write output to -.Ar outfile , -which may be -.Qq \- -for stdout. -.It Fl W -Print warnings to stderr. +utility interfaces the +.Xr mdoc 3 +library to scan, parse and validate mdoc-macro documents. Arguments +follow: +.Bl -tag -width "\-Werr... " +.It Fl W Ns Ar err... +Print warning messages. May be set to +.Fl W Ns Ar all +for all warnings, +.Ar compat +for groff/troff-compatibility warnings, or +.Ar syntax +for syntax warnings. If +.Fl W Ns Ar error +is specified, warnings are considered errors and cause utility +termination. Multiple +.Fl W +arguments may be comma-separated, such as +.Fl W Ns Ar error,all . +.It Fl v +Print verbose parsing output. .It Ar infile Read input from .Ar infile , which may be -.Qq \- +.Dq \- for stdin. .El .Pp +Parsing and validation rules are drawn entirely from the +.Xr mdoc 7 +and +.Xr mdoc.samples 7 +manuals. +.Pp By default, .Nm -reads from stdin and writes to stdout using the xml filter. +reads from stdin, writes messages to stdout, and writes errors and +warnings to stderr. +.Pp +.Ex -std mdocml +.Pp +.Nm +is +.Ud +.\" +.Sh EXAMPLES +To validate this manual page: +.Pp +.D1 % mdocml \-Wall,error mdocml.1 .\" -.Ss XML Filter -The XML filter, specified by -.Fl f Ar xml , -is the default filter. It creates an XML document where element names are -their respective roff macro names. Each element name has an associated -namespace, which is one of -.Qq block , -.Qq head , -.Qq body , -or -.Qq inline , -corresponding to the display mode of a node. The document root is -always the -.Qq mdoc -element, in the default namespace. -.\" This next request is for sections 1, 6, 7 & 8 only. -.\" .Sh ENVIRONMENT -.\" .Sh SEE ALSO .Xr groff 1 , .Xr mdoc.samples 7 , -.Xr mdoc 7 +.Xr mdoc 7 , +.Xr mdoc 3 .\" .Sh STANDARDS .\" .Sh HISTORY .Sh AUTHORS The .Nm utility was written by -.An Em Kristaps Dzonsons Aq kristaps@kth.se . +.An Kristaps Dzonsons Aq kristaps@kth.se . .\" .Sh CAVEATS -Most caveats of +The most glaring short-coming of .Nm -stem from ambiguities in -.Xr mdoc 7 -or the necessary limitations of converting an ad hoc language into -structured ones: -.Bl -enum -compact -offset indent -.It -The engine doesn't understand the -.Sq \&Xo , -.Sq \&Xc , -.Sq \&No , -.Sq \&Db , -.Sq \&Xc , +is that it doesn't yet support the +.Sq \&Xc and .Sq \&Xo -mdoc macros. -.It -All macro arguments may be quoted, instead of only some. -.It -Blank lines raise errors. -.It -If terminating punctuation is found, then -.Em all -remaining tokens are flushed after line scope is closed, not just the -last one. -.El -.Pp -The roff engine in -.Nm -produces text in-line; thus, output may already be partially written by -the time an error is encountered. +macros when used to extend the line arguments to +.Sq \&It ; +in effect, trampling the body section. We note that this is explicitly +discouraged in +.Xr mdoc.samples 7 , +but in practice used quite often. .\" .Sh BUGS