Annotation of mandoc/mdocml.1, Revision 1.25
1.1 kristaps 1: .\"
1.2 kristaps 2: .Dd $Mdocdate$
1.25 ! kristaps 3: .Dt mdocml 1
1.1 kristaps 4: .Os
1.3 kristaps 5: .\"
1.1 kristaps 6: .Sh NAME
1.2 kristaps 7: .Nm mdocml
8: .Nd compile manpage source into mark-up language
1.3 kristaps 9: .\"
1.1 kristaps 10: .Sh SYNOPSIS
1.2 kristaps 11: .Nm mdocml
1.24 kristaps 12: .Op Fl v
13: .Op Fl W Ns Ar err...
1.7 kristaps 14: .Op Fl f Ar filter
1.2 kristaps 15: .Op Fl o Ar outfile
16: .Op Ar infile
1.3 kristaps 17: .\"
1.1 kristaps 18: .Sh DESCRIPTION
19: The
20: .Nm
1.13 kristaps 21: utility parses mdoc formatted manual source and passes results into an
1.17 kristaps 22: output filter. The current output filters are
23: .Ar html
24: and
1.10 kristaps 25: .Ar xml ,
1.17 kristaps 26: the default. Arguments common to all filters follow:
1.10 kristaps 27: .Bl -tag -width "\-o outfile"
28: .It Fl f Ar filter
1.25 ! kristaps 29: The output filter name. This
! 30: .Em must
! 31: be declared before any other options.
1.10 kristaps 32: .It Fl o Ar outfile
1.12 kristaps 33: Write output to
1.2 kristaps 34: .Ar outfile ,
35: which may be
1.21 kristaps 36: .Dq \-
1.12 kristaps 37: for stdout.
1.24 kristaps 38: .It Fl W Ns Ar err...
39: Print warning messages. If set to
40: .Fl W Ns Ar all ,
41: all warnings are printed; if
42: .Fl W Ns Ar error ,
43: warnings are considered errors and cause utility termination. Multiple
44: .Fl W
45: arguments may be comma-separated, such as
46: .Fl W Ns Ar error,all .
1.23 kristaps 47: .It Fl v
48: Make warning and error messages verbose.
1.2 kristaps 49: .It Ar infile
50: Read input from
51: .Ar infile ,
52: which may be
1.21 kristaps 53: .Dq \-
1.12 kristaps 54: for stdin.
1.2 kristaps 55: .El
1.12 kristaps 56: .Pp
57: By default,
58: .Nm
59: reads from stdin and writes to stdout using the xml filter.
1.20 kristaps 60: .Pp
61: .Ex -std mdocml
1.12 kristaps 62: .\"
1.10 kristaps 63: .Ss XML Filter
64: The XML filter, specified by
65: .Fl f Ar xml ,
1.17 kristaps 66: is the default filter. This filter has no additional arguments.
67: .Pp
68: The XML filter creates an XML document where element names are their respective
69: roff macro names. Each element name has an associated
1.10 kristaps 70: namespace, which is one of
1.21 kristaps 71: .Dq block ,
72: .Dq head ,
73: .Dq body ,
1.12 kristaps 74: or
1.21 kristaps 75: .Dq inline ,
1.12 kristaps 76: corresponding to the display mode of a node. The document root is
77: always the
1.21 kristaps 78: .Dq mdoc
1.17 kristaps 79: element, in the default namespace; the
1.21 kristaps 80: .Dq head
1.17 kristaps 81: namespace is for block headers (such as
82: .Sq .Ss
83: and
84: .Sq .Sh ) ;
85: the
1.21 kristaps 86: .Dq body
1.17 kristaps 87: namespace is for block bodies; and the
1.21 kristaps 88: .Dq inline
1.17 kristaps 89: namespace is for in-line elements (such as
90: .Sq .Em ) .
91: .Ss HTML Filter
92: The HTML filter, specified by
93: .Fl f Ar html ,
94: accepts the following filter-specific arguments:
95: .Bl -tag -width "\-c css"
96: .It Fl c Ar css
97: The CSS file location, which defaults to
98: .Ar mdocml.css .
99: .It Fl e
100: Whether to embed the CSS file into the HTML prologue.
101: .El
1.18 kristaps 102: .\"
1.17 kristaps 103: .Sh EXAMPLES
104: To produce an HTML4-strict document
105: .Pa mdocml.html
106: for
107: .Pa mdocml.1
108: with the default, embedded style-sheet:
109: .Pp
1.18 kristaps 110: .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
1.17 kristaps 111: .Pp
112: To create an XML document on standard output from
113: .Pa mdocml.1
114: with the default namespace identifiers
115: .Li head ,
116: .Li body ,
117: .Li block
118: and
119: .Li inline :
120: .Pp
121: .D1 % mdocml mdocml.1
1.12 kristaps 122: .\"
1.3 kristaps 123: .Sh SEE ALSO
124: .Xr groff 1 ,
125: .Xr mdoc.samples 7 ,
126: .Xr mdoc 7
1.1 kristaps 127: .\" .Sh STANDARDS
128: .\" .Sh HISTORY
1.3 kristaps 129: .Sh AUTHORS
130: The
131: .Nm
132: utility was written by
1.22 kristaps 133: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.3 kristaps 134: .\"
135: .Sh CAVEATS
1.7 kristaps 136: Most caveats of
1.3 kristaps 137: .Nm
1.7 kristaps 138: stem from ambiguities in
139: .Xr mdoc 7
140: or the necessary limitations of converting an ad hoc language into
141: structured ones:
142: .Bl -enum -compact -offset indent
143: .It
1.12 kristaps 144: The engine doesn't understand the
145: .Sq \&No ,
146: .Sq \&Db ,
147: .Sq \&Xc ,
148: and
1.3 kristaps 149: .Sq \&Xo
1.12 kristaps 150: mdoc macros.
1.7 kristaps 151: .It
152: All macro arguments may be quoted, instead of only some.
153: .It
1.12 kristaps 154: Blank lines raise errors.
1.7 kristaps 155: .It
1.9 kristaps 156: If terminating punctuation is found, then
157: .Em all
158: remaining tokens are flushed after line scope is closed, not just the
159: last one.
1.7 kristaps 160: .El
1.14 kristaps 161: .Pp
162: The roff engine in
163: .Nm
164: produces text in-line; thus, output may already be partially written by
165: the time an error is encountered.
1.1 kristaps 166: .\" .Sh BUGS
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdocml.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc