.\"	$OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
.\"
.\" The following requests are required for all man pages.
.\"
.\" Remove `\&' from the line below.
.Dd $Mdocdate$
.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
.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 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 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
.\" 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 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
.Sq \&Xo
and
.Sq \&Xc
troff macros.
.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