===================================================================
RCS file: /cvs/mandoc/Attic/mdocml.1,v
retrieving revision 1.16
retrieving revision 1.25
diff -u -p -r1.16 -r1.25
--- mandoc/Attic/mdocml.1	2008/12/03 19:21:58	1.16
+++ mandoc/Attic/mdocml.1	2008/12/10 12:05:33	1.25
@@ -1,5 +1,5 @@
 .\"
-.Dd $Mdocdate: December 3 2008 $
+.Dd $Mdocdate: December 10 2008 $
 .Dt mdocml 1
 .Os
 .\"
@@ -9,7 +9,8 @@
 .\"
 .Sh SYNOPSIS
 .Nm mdocml
-.Op Fl W
+.Op Fl v
+.Op Fl W Ns Ar err...
 .Op Fl f Ar filter
 .Op Fl o Ar outfile
 .Op Ar infile
@@ -18,49 +19,106 @@
 The
 .Nm
 utility parses mdoc formatted manual source and passes results into an
-output filter.  The only current output filter is
+output filter.  The current output filters are
+.Ar html
+and
 .Ar xml ,
-the default.  The arguments are as follows:
+the default.  Arguments common to all filters follow:
 .Bl -tag -width "\-o outfile"
 .It Fl f Ar filter
-The output filter name.
+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
-.Qq \-
+.Dq \-
 for stdout.
-.It Fl W
-Print warnings to stderr.
+.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 
+.Fl W
+arguments may be comma-separated, such as
+.Fl W Ns Ar error,all .
+.It Fl v
+Make warning and error messages verbose.
 .It Ar infile
 Read input from
 .Ar infile ,
 which may be 
-.Qq \-
+.Dq \-
 for stdin.
 .El
 .Pp
 By default,
 .Nm
 reads from stdin and writes to stdout using the xml filter.
+.Pp
+.Ex -std mdocml
 .\"
 .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
+is the default filter.  This filter has no additional arguments.
+.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 
-.Qq block ,
-.Qq head ,
-.Qq body ,
+.Dq block ,
+.Dq head ,
+.Dq body ,
 or
-.Qq inline ,
+.Dq 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
+.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
+.\" 
+.Sh EXAMPLES
+To produce an HTML4-strict document 
+.Pa mdocml.html
+for
+.Pa mdocml.1 
+with the default, embedded style-sheet:
+.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 
 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,
@@ -72,7 +130,7 @@ element, in the default namespace.
 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
@@ -84,8 +142,6 @@ structured ones:
 .Bl -enum -compact -offset indent
 .It 
 The engine doesn't understand the
-.Sq \&Xo ,
-.Sq \&Xc ,
 .Sq \&No ,
 .Sq \&Db ,
 .Sq \&Xc ,