.\"
.Dd $Mdocdate: December 10 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
is a full macro parser operating on source documents, specifically mdoc,
validating input and compiling to HTML and XML output types.
.Pp
Downloads (source and ports) are available in the
.Sx DOWNLOADS
section.
.Pp
The
.Nm
utility is tested specifically on
.Ox 
manual sources as compiled and invoked both on 
.Ox
and Linux.
.Nm
is
.Ud 
.\"
.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 
valid special characters (such as
.Sq \en
and
.Sq \et ) ,
.It 
sane macro scope (such as
.Sq \&.Sh
macros clobbering a pending
.Sq \&.Bl
scope),
.It 
valid predefined characters (such as \\*(>= and \\*q),
.It
correctly-ordered prelude and sections,
.It
sane macro argument values (such as those for 
.Sq \&.Dt
or
.Sq \&.Sm ) ,
.It
valid manual sections and systems;
.It
and so on.
.El
.\"
.Ss Filtering
When a line of source has been parsed, it's passed to the output
filters, which format and display data.  The two available filters are
HTML and XML.
.Pp
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.  A sample is available at
http://mdocml.bsd.lv/index.xml
.Ns .
.\" 
.Sh DOWNLOADS
Download 
.Nm
at http://mdocml.bsd.lv/mdocml.tgz
.Ns . 
.\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
The current version is 1.0.2, dated 10/12/2008.
.\" ------------------------------------------------------------------
.Pp
Previous versions are archived as mdocml-x.y.z.tgz, with the appropriate
versions filled in.
.\" 
.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 -Wall -e -o index.html index.7
.Pp
The original mdoc source is at http://mdocml.bsd.lv/index.txt 
.Ns .
.\"
.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.
.It Xr roffit Ns : http://daniel.haxx.se/projects/roffit/
HTML from roff manual source.  Dead project?
.El
.\"
.Sh AUTHORS
The
.Nm
utility was written by 
.An Kristaps Dzonsons Aq kristaps@kth.se .