.\"	$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: November 28 2008 $
.Dt mdocml 1
.Os
.\"
.Sh NAME
.Nm mdocml
.Nd compile manpage source into mark-up language
.\"
.Sh SYNOPSIS
.Nm mdocml
.Op Fl vW
.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 validate ,
the default.  The arguments are as follows:
.Bl -tag -width "\-o outfile"
.It Fl o Ar outfile
Place output in 
.Ar outfile ,
which may be
.Qq \-
for standard output.  The default is standard output.
.It Ar infile
Read input from
.Ar infile ,
which may be 
.Qq \-
for standard input.  The default is standard input.
.It Fl v
Print messages (output depends on filter).
.It Fl W
Print warnings (output depends on filter).
.El
.Ss Validate Filter
The validate filter, specified by
.Fl f Ar validate ,
is the default filter.  It produces no output, so specifying
.Fl o Ar outfile
results in an empty file.
.\" 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 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 
Non-ascii characters may cause issues.
.El
.\" .Sh BUGS