===================================================================
RCS file: /cvs/mandoc/Attic/mdocml.1,v
retrieving revision 1.1
retrieving revision 1.23
diff -u -p -r1.1 -r1.23
--- mandoc/Attic/mdocml.1	2008/11/22 14:53:29	1.1
+++ mandoc/Attic/mdocml.1	2008/12/08 16:29:57	1.23
@@ -1,40 +1,156 @@
-.\"	$OpenBSD: mdocml.1,v 1.1 2008/11/22 14:53:29 kristaps Exp $
 .\"
-.\" The following requests are required for all man pages.
-.\"
-.\" Remove `\&' from the line below.
-.Dd $\&Mdocdate$
-.Dt NAME SECTION#
+.Dd $Mdocdate: December 8 2008 $
+.Dt mdocml 1 alpha
 .Os
+.\"
 .Sh NAME
-.Nm program
-.Nd one line about what it does
+.Nm mdocml
+.Nd compile manpage source into mark-up language
+.\"
 .Sh SYNOPSIS
-.\" For a program:  program [-abc] file ...
-.Nm program
-.Op Fl abc
-.Ar
+.Nm mdocml
+.Op Fl vW
+.Op Fl f Ar filter
+.Op Fl o Ar outfile
+.Op Ar infile
+.\"
 .Sh DESCRIPTION
 The
 .Nm
-utility processes files ...
-something
-something.
-.\" The following requests should be uncommented and used where appropriate.
-.\" This next request is for sections 2, 3, and 9 function return values only.
-.\" .Sh RETURN VALUES
-.\" This next request is for sections 1, 6, 7 & 8 only.
-.\" .Sh ENVIRONMENT
-.\" .Sh FILES
-.\" .Sh EXAMPLES
-.\" This next request is for sections 1, 4, 6, and 8 only.
-.\" .Sh DIAGNOSTICS
-.\" The next request is for sections 2, 3, and 9 error and signal handling only.
-.\" .Sh ERRORS
-.\" .Sh SEE ALSO
-.\" .Xr foobar 1
+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.
+.It Fl o Ar outfile
+Write output to 
+.Ar outfile ,
+which may be
+.Dq \-
+for stdout.
+.It Fl W
+Print warnings to stderr.
+.It Fl v
+Make warning and error messages verbose.
+.It Ar infile
+Read input from
+.Ar infile ,
+which may be 
+.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.  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 
+.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
+.\" 
+.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 ,
+.Xr mdoc.samples 7 ,
+.Xr mdoc 7
 .\" .Sh STANDARDS
 .\" .Sh HISTORY
-.\" .Sh AUTHORS
-.\" .Sh CAVEATS
+.Sh AUTHORS
+The
+.Nm
+utility was written by 
+.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\"
+.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