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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.\"
.Dd $Mdocdate: December 10 2008 $
.Dt mdocml 1
.Os
.\"
.Sh NAME
.Nm mdocml
.Nd compile manpage source into mark-up language
.\"
.Sh SYNOPSIS
.Nm mdocml
.Op Fl v
.Op Fl W Ns Ar err...
.Op Fl f Ar filter
.Op Fl o Ar outfile
.Op Ar infile
.\"
.Sh DESCRIPTION
The
.Nm
utility parses mdoc formatted manual source and passes results into an
output filter. The current output filters are
.Fl f Ar html
and
.Fl f Ar xml .
By default,
.Nm
only validates its input. This may be explicitly directed with
.Fl f Ar noop .
Arguments common to all filters follow:
.Bl -tag -width "\-o outfile"
.It Fl f Ar filter
The output filter name.
.It Fl o Ar outfile
Write output to
.Ar outfile ,
which may be
.Dq \-
for stdout. This is meaningless for
.Fl f Ar noop .
.It Fl W Ns Ar err...
Print warning messages. If set to
.Fl W Ns Ar all ,
all warnings are printed; if
.Fl W Ns Ar error ,
warnings are considered errors and cause utility termination. Multiple
.Fl W
arguments may be comma-separated, such as
.Fl W Ns Ar error,all .
.It Fl v
Make warning and error messages verbose.
.It Ar infile
Read input from
.Ar infile ,
which may be
.Dq \-
for stdin.
.El
.Pp
By default,
.Nm
reads from stdin and writes to stdout.
.Pp
.Ex -std mdocml
.\"
.Ss Noop Filter
The default noop
.Dq validating
filter simply validates its input; it produces no output beyond error
and warning messages.
.\"
.Ss XML Filter
The XML filter, specified by
.Fl f Ar xml ,
produces correctly-formatted XML output. This filter has no additional
arguments.
.Pp
The XML filter creates an XML document where element names are their respective
roff macro names. Each element name has an associated
namespace, which is one of
.Dq block ,
.Dq head ,
.Dq body ,
or
.Dq inline ,
corresponding to the display mode of a node. The document root is
always the
.Dq mdoc
element, in the default namespace; the
.Dq head
namespace is for block headers (such as
.Sq .Ss
and
.Sq .Sh ) ;
the
.Dq body
namespace is for block bodies; and the
.Dq inline
namespace is for in-line elements (such as
.Sq .Em ) .
.\"
.Ss HTML Filter
The HTML filter, specified by
.Fl f Ar html ,
accepts the following filter-specific arguments:
.Bl -tag -width "\-c css"
.It Fl c Ar css
The CSS file location, which defaults to
.Ar mdocml.css .
.It Fl e
Whether to embed the CSS file into the HTML prologue.
.El
.Pp
By default, the HTML filter produces HTML-4.01 strict mark-up. The
default CSS document styles the page as it would appear in a terminal
window.
.\"
.Sh EXAMPLES
To produce an HTML4-strict document
.Pa mdocml.html
for
.Pa mdocml.1
with the default, embedded style-sheet:
.Pp
.D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
.Pp
To create an XML document on standard output from
.Pa mdocml.1
with the default namespace identifiers
.Li head ,
.Li body ,
.Li block
and
.Li inline :
.Pp
.D1 % mdocml -Wall,error -fxml mdocml.1
.Pp
The previous example will also halt on input document warnings.
.\"
.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 the
.Sq \&No ,
.Sq \&Db ,
.Sq \&Xc ,
and
.Sq \&Xo
mdoc macros.
.It
All macro arguments may be quoted, instead of only some.
.It
Blank lines raise errors.
.It
If terminating punctuation is found, then
.Em all
remaining tokens are flushed after line scope is closed, not just the
last one.
.El
.Pp
The roff engine in
.Nm
produces text in-line; thus, output may already be partially written by
the time an error is encountered.
.\" .Sh BUGS
|
