.\"
.Dd $Mdocdate: December 2 2008 $
.Dt mdocml 1
.Os
.\"
.Sh NAME
.Nm mdocml
.Nd compile manpage source into mark-up language
.\"
.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 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.
.It Ar infile
Read input from
.Ar infile ,
which may be 
.Qq \-
for stdin.
.El
.Pp
By default,
.Nm
reads from stdin and writes to stdout using the xml filter.
.\"
.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 
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
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
The
.Nm
utility was written by 
.An Em 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 \&Xo ,
.Sq \&Xc ,
.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