.\"
.Dd $Mdocdate: December 7 2008 $
.Dt index 7 
.Os LOCAL
.\"
.Sh NAME
.Nm mdocml
.Nd compile mdoc macros into mark-up language
.\"
.Sh DESCRIPTION
The
.Nm 
utility compiles 
.Xr mdoc 7
macros, such as those inheriting from
.Xr mdoc.samples 7 , 
into XML or HTML documents.  Unlike other similar utilities such as 
.Xr rman 1
and
.Xr man2html 1 ,
.Nm
acts directly on source documents, validating its input and producing a
variety of outputs.
.\"
.Ss Validation
In order to operate sanely,
.Nm
fully validates its input.  This includes, but is not limited to, the
following checks:
.Pp
.Bl -enum -compact
.It 
special characters (such as
.Sq \en
and
.Sq \et ) ,
.It 
macro scope (such as
.Sq \&.Sh
macros clobbering a pending
.Sq \&.Bl
scope),
.It 
predefined characters (such as \\*(>= and \\*q),
.It
correctly-ordered document prelude,
.It
sane argument values (such as those for 
.Sq \&.Dt
or
.Sq \&.Sm ) ,
.It
and so on.
.El
.Pp
The
.Nm
utility has been tested under Linux and 
.Ox ,
specifically on
.Ox 
manual source.
.Nm
is
.Ud 
.\"
.Ss Filtering
When a block of source has been verified, it's passed to the front-end
fitlers, which format and display data.  The
.Nm
utility is invoked with a filter by the
.Fl f
flag.  The HTML filter has the following features:
.Pp
.Bl -enum -compact
.It
HTML-4.01 strict compliance.
.It
Proper render of values in UTF-8, such as
.Dq quotes
and \*(>= predefined values.
.It
URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
.It
CSS-dictated style with meaningful non-CSS defaults.
.El
.Pp
The XML filter creates a correct XML tree with 
.Dq block ,
.Dq head ,
.Dq body ,
and
.Dq inline
namespaces corresponding to macro categories.  Namespace identifiers
correspond to their definitions.
.\" 
.Sh DOWNLOADS
Download 
.Nm
at http://mdocml.bsd.lv/mdocml.tgz
.Ns . 
.\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
The current version is 1.0.0, dated 08/12/2008.
.\" ------------------------------------------------------------------
.\" 
.Sh DOCUMENTS
The manual for 
.Nm
is available at http://mdocml.bsd.lv/mdocml.html
.Ns .
.\" 
.Sh EXAMPLES
This page was produced as follows:
.Pp
.D1 % mdocml -fhtml -W -e -o index.html index.7
.\"
.Sh SEE ALSO
.Bl -ohang
.It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
Accepts either formatted roff output or source and produces HTML output.
.It Xr man2html Ns : http://www.nongnu.org/man2html/
Accepts formatted
.Xr nroff 1
text and produces HTML output.
.It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
.Fx
and
.Ox 
project CGI for producing HTML from nroff source.
.El
.\"
.Sh AUTHORS
The
.Nm
utility was written by 
.An Kristaps Dzonsons Aq kristaps@kth.se .