===================================================================
RCS file: /cvs/mandoc/Attic/mdocml.1,v
retrieving revision 1.6
retrieving revision 1.10
diff -u -p -r1.6 -r1.10
--- mandoc/Attic/mdocml.1	2008/11/27 17:27:50	1.6
+++ mandoc/Attic/mdocml.1	2008/11/30 21:41:35	1.10
@@ -1,13 +1,12 @@
-.\"	$OpenBSD: mdocml.1,v 1.6 2008/11/27 17:27:50 kristaps Exp $
+.\"	$OpenBSD: mdocml.1,v 1.10 2008/11/30 21:41:35 kristaps Exp $
 .\"
 .\" The following requests are required for all man pages.
 .\"
 .\" Remove `\&' from the line below.
-.Dd $Mdocdate: November 27 2008 $
+.Dd $Mdocdate: November 30 2008 $
 .Dt mdocml 1
 .Os
 .\"
-.Op foo
 .Sh NAME
 .Nm mdocml
 .Nd compile manpage source into mark-up language
@@ -15,30 +14,62 @@
 .Sh SYNOPSIS
 .Nm mdocml
 .Op Fl W
+.Op Fl f Ar filter
 .Op Fl o Ar outfile
 .Op Ar infile
 .\"
 .Sh DESCRIPTION
 The
 .Nm
-utility compiles manpage source into a mark-up language.  Its arguments
-are as follows:
+utility parses
+.Xr mdoc
+formatted manual source and passes results into the output filter
+dictated by 
+.Fl f Ar 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, which defaults to
+.Ar xml .
 .It Fl o Ar outfile
 Place output in 
 .Ar outfile ,
 which may be
 .Qq \-
-for standard output.  The default is standard output.
+for stdout.  The default is stdout.
+.It Fl W
+Print compiler warnings to stderr.
 .It Ar infile
 Read input from
 .Ar infile ,
 which may be 
 .Qq \-
-for standard input.  The default is standard input.
-.It Fl W
-Print warnings.
+for stdin.  The default is stdin.
 .El
+.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 inline ,
+or
+.Qq special ,
+corresponding to the display mode of a node.
+.Pp
+Sample output follows:
+.Bd -literal
+<?xml version="1.0" encoding="UTF-8"?>
+<block:mdoc>
+  <block:Sh>
+    <inline:Sh>NAME</inline:Sh> <inline:Nm>example</inline:Nm>
+    <inline:Nd>example text</inline:Nd>
+  </block:Sh>
+</block:mdoc>
+.Ed
 .\" 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
@@ -60,17 +91,30 @@ Print warnings.
 The
 .Nm
 utility was written by 
-.An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Em Kristaps Dzonsons Aq kristaps@kth.se .
 .\"
 .Sh CAVEATS
-The
+Most caveats of
 .Nm
-engine doesn't understand
+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
 .Sq \&Xo
 and
 .Sq \&Xc
 troff macros.
-.Pp
-.Em All
-macro arguments may be quoted, instead of only some.
+.It 
+All macro arguments may be quoted, instead of only some.
+.It 
+Blank lines raise warnings.
+.It 
+If terminating punctuation is found, then 
+.Em all
+remaining tokens are flushed after line scope is closed, not just the
+last one.
+.El
 .\" .Sh BUGS