1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
.\"
.Dd $Mdocdate$
.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
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 document prelude,
.It
sane macro argument values (such as those for
.Sq \&.Dt
or
.Sq \&.Sm ) ,
.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.0, dated 08/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 -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 .
|
