version 1.3, 2008/12/04 19:31:57 |
version 1.11, 2008/12/10 13:15:55 |
|
|
.\" |
.\" |
.Sh NAME |
.Sh NAME |
.Nm mdocml |
.Nm mdocml |
.Nd compile manpage source into mark-up language |
.Nd compile mdoc macros into mark-up language |
.\" |
.\" |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
Line 19 into XML or HTML documents. Unlike other similar util |
|
Line 19 into XML or HTML documents. Unlike other similar util |
|
and |
and |
.Xr man2html 1 , |
.Xr man2html 1 , |
.Nm |
.Nm |
acts directly on source documents, validating its input and producing a |
is a full macro parser operating on source documents, specifically mdoc, |
variety of outputs. |
validating input and compiling to HTML and XML output types. |
|
.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 |
.Ss Validation |
In order to operate sanely, |
In order to operate sanely, |
Line 30 following checks: |
|
Line 41 following checks: |
|
.Pp |
.Pp |
.Bl -enum -compact |
.Bl -enum -compact |
.It |
.It |
special characters (such as |
valid special characters (such as |
.Sq \en |
.Sq \en |
and |
and |
.Sq \et ) , |
.Sq \et ) , |
.It |
.It |
macro scope (such as |
sane macro scope (such as |
.Sq \&.Sh |
.Sq \&.Sh |
macros clobbering a pending |
macros clobbering a pending |
.Sq \&.Bl |
.Sq \&.Bl |
scope), |
scope), |
.It |
.It |
predefined characters (such as \\*(>= and \\*q, rendering as \*(>= and \*q, |
valid predefined characters (such as \\*(>= and \\*q), |
respectively), |
|
.It |
.It |
correctly-ordered document prelude, |
correctly-ordered prelude and sections, |
.It |
.It |
sane argument values (such as those for |
sane macro argument values (such as those for |
.Sq \&.Dt |
.Sq \&.Dt |
or |
or |
.Sq \&.Sm ) , |
.Sq \&.Sm ) , |
.It |
.It |
|
valid manual sections and systems; |
|
.It |
and so on. |
and so on. |
.El |
.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 |
.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 ENVIRONMENT |
.Sh DOWNLOADS |
The |
Download |
.Nm |
.Nm |
utility has been tested under Linux and OpenBSD. |
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 |
.Sh EXAMPLES |
This page was produced as follows: |
This page was produced as follows: |
.Pp |
.Pp |
.D1 % mdocml -fhtml -o index.html index.7 |
.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 |
.Sh SEE ALSO |
TODO. |
.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 |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Em Kristaps Dzonsons Aq kristaps@kth.se . |
.An Kristaps Dzonsons Aq kristaps@kth.se . |