===================================================================
RCS file: /cvs/mandoc/Attic/mdocml.1,v
retrieving revision 1.25
retrieving revision 1.33
diff -u -p -r1.25 -r1.33
--- mandoc/Attic/mdocml.1	2008/12/10 12:05:33	1.25
+++ mandoc/Attic/mdocml.1	2009/02/21 15:34:46	1.33
@@ -1,51 +1,53 @@
 .\"
-.Dd $Mdocdate: December 10 2008 $
+.Dd $Mdocdate: February 21 2009 $
 .Dt mdocml 1
 .Os
-.\"
+.\" SECTION
 .Sh NAME
 .Nm mdocml
-.Nd compile manpage source into mark-up language
-.\"
+.Nd mdoc macro compiler
+.\" SECTION
 .Sh SYNOPSIS
 .Nm mdocml
+.Op Fl f Ns Ar filter
 .Op Fl v
 .Op Fl W Ns Ar err...
-.Op Fl f Ar filter
-.Op Fl o Ar outfile
 .Op Ar infile
-.\"
+.\" SECTION
 .Sh DESCRIPTION
 The
 .Nm
-utility parses mdoc formatted manual source and passes results into an
-output filter.  The current output filters are
-.Ar html
-and
-.Ar xml ,
-the default.  Arguments common to all filters follow:
-.Bl -tag -width "\-o outfile"
-.It Fl f Ar filter
-The output filter name.  This
-.Em must
-be declared before any other options.
-.It Fl o Ar outfile
-Write output to 
-.Ar outfile ,
-which may be
-.Dq \-
-for stdout.
+utility interfaces the
+.Xr mdoc 3
+library to scan, parse, validate and output mdoc-macro documents.
+Arguments follow:
+.Bl -tag -width "\-Werr... "
+.\" ITEM
+.It Fl f Ns Ar filter
+Pipe the parsed syntax tree into an output filter.  May be either
+.Ar tree
+for the parse tree or
+.Ar term
+for a terminal-encoded, formatted manual page.
+.\" ITEM
+.It Fl v
+Print verbose parsing output.
+.\" ITEM
 .It Fl W Ns Ar err...
-Print warning messages.  If set to 
-.Fl W Ns Ar all ,
-all warnings are printed; if
-.Fl W Ns Ar error ,
-warnings are considered errors and cause utility termination.  Multiple 
+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
-Make warning and error messages verbose.
+.\" ITEM
 .It Ar infile
 Read input from
 .Ar infile ,
@@ -53,114 +55,46 @@ which may be 
 .Dq \-
 for stdin.
 .El
+.\" PARAGRAPH
 .Pp
+Parsing and validation rules are drawn entirely from the 
+.Xr mdoc 7
+and
+.Xr mdoc.samples 7 
+manuals.
+.\" PARAGRAPH
+.Pp
 By default,
 .Nm
-reads from stdin and writes to stdout using the xml filter.
+reads from stdin and only validates its input.
+.\" PARAGRAPH
 .Pp
 .Ex -std mdocml
-.\"
-.Ss XML Filter
-The XML filter, specified by
-.Fl f Ar xml ,
-is the default filter.  This filter has no additional arguments.
+.\" PARAGRAPH
 .Pp
-The XML filter creates an XML document where element names are their respective
-roff macro names.  Each element name has an associated
-namespace, which is one of 
-.Dq block ,
-.Dq head ,
-.Dq body ,
-or
-.Dq inline ,
-corresponding to the display mode of a node.  The document root is
-always the
-.Dq mdoc
-element, in the default namespace; the 
-.Dq head
-namespace is for block headers (such as 
-.Sq .Ss
-and
-.Sq .Sh ) ;
-the
-.Dq body
-namespace is for block bodies; and the
-.Dq inline
-namespace is for in-line elements (such as
-.Sq .Em ) .
-.Ss HTML Filter
-The HTML filter, specified by
-.Fl f Ar html ,
-accepts the following filter-specific arguments:
-.Bl -tag -width "\-c css"
-.It Fl c Ar css
-The CSS file location, which defaults to 
-.Ar mdocml.css .
-.It Fl e
-Whether to embed the CSS file into the HTML prologue.
-.El
-.\" 
+.Nm
+is
+.Ud
+.\" SECTION
 .Sh EXAMPLES
-To produce an HTML4-strict document 
-.Pa mdocml.html
-for
-.Pa mdocml.1 
-with the default, embedded style-sheet:
+To validate this manual page:
+.\" PARAGRAPH
 .Pp
-.D1 % mdocml -fhtml -e -o mdocml.html mdocml.1 
-.Pp
-To create an XML document on standard output from
-.Pa mdocml.1
-with the default namespace identifiers
-.Li head ,
-.Li body ,
-.Li block 
-and
-.Li inline :
-.Pp
-.D1 % mdocml mdocml.1 
-.\"
+.D1 % mdocml \-Wall,error mdocml.1 
+.\" SECTION
 .Sh SEE ALSO
 .Xr groff 1 ,
 .Xr mdoc.samples 7 ,
-.Xr mdoc 7
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Xr mdoc 7 ,
+.Xr mdoc 3
+.\" 
 .Sh AUTHORS
 The
 .Nm
 utility was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .
-.\"
+.\" SECTION
 .Sh CAVEATS
-Most caveats 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 \&No ,
-.Sq \&Db ,
-.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.
-.\" .Sh BUGS
+See
+.Xr mdoc 3
+for a list of bugs, caveats, and incomplete macros.