Annotation of mandoc/mdocml.1, Revision 1.26
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
1.26 ! kristaps 23: .Fl f Ar html
1.17 kristaps 24: and
1.26 ! kristaps 25: .Fl f Ar xml .
! 26: By default,
! 27: .Nm
! 28: only validates its input. This may be explicitly directed with
! 29: .Fl f Ar noop .
! 30: Arguments common to all filters follow:
1.10 kristaps 31: .Bl -tag -width "\-o outfile"
32: .It Fl f Ar filter
1.26 ! kristaps 33: The output filter name.
1.10 kristaps 34: .It Fl o Ar outfile
1.12 kristaps 35: Write output to
1.2 kristaps 36: .Ar outfile ,
37: which may be
1.21 kristaps 38: .Dq \-
1.26 ! kristaps 39: for stdout. This is meaningless for
! 40: .Fl f Ar noop .
1.24 kristaps 41: .It Fl W Ns Ar err...
42: Print warning messages. If set to
43: .Fl W Ns Ar all ,
44: all warnings are printed; if
45: .Fl W Ns Ar error ,
46: warnings are considered errors and cause utility termination. Multiple
47: .Fl W
48: arguments may be comma-separated, such as
49: .Fl W Ns Ar error,all .
1.23 kristaps 50: .It Fl v
51: Make warning and error messages verbose.
1.2 kristaps 52: .It Ar infile
53: Read input from
54: .Ar infile ,
55: which may be
1.21 kristaps 56: .Dq \-
1.12 kristaps 57: for stdin.
1.2 kristaps 58: .El
1.12 kristaps 59: .Pp
60: By default,
61: .Nm
1.26 ! kristaps 62: reads from stdin and writes to stdout.
1.20 kristaps 63: .Pp
64: .Ex -std mdocml
1.12 kristaps 65: .\"
1.26 ! kristaps 66: .Ss Noop Filter
! 67: The default noop
! 68: .Dq validating
! 69: filter simply validates its input; it produces no output beyond error
! 70: and warning messages.
! 71: .\"
1.10 kristaps 72: .Ss XML Filter
73: The XML filter, specified by
74: .Fl f Ar xml ,
1.26 ! kristaps 75: produces correctly-formatted XML output. This filter has no additional
! 76: arguments.
1.17 kristaps 77: .Pp
78: The XML filter creates an XML document where element names are their respective
79: roff macro names. Each element name has an associated
1.10 kristaps 80: namespace, which is one of
1.21 kristaps 81: .Dq block ,
82: .Dq head ,
83: .Dq body ,
1.12 kristaps 84: or
1.21 kristaps 85: .Dq inline ,
1.12 kristaps 86: corresponding to the display mode of a node. The document root is
87: always the
1.21 kristaps 88: .Dq mdoc
1.17 kristaps 89: element, in the default namespace; the
1.21 kristaps 90: .Dq head
1.17 kristaps 91: namespace is for block headers (such as
92: .Sq .Ss
93: and
94: .Sq .Sh ) ;
95: the
1.21 kristaps 96: .Dq body
1.17 kristaps 97: namespace is for block bodies; and the
1.21 kristaps 98: .Dq inline
1.17 kristaps 99: namespace is for in-line elements (such as
100: .Sq .Em ) .
1.26 ! kristaps 101: .\"
1.17 kristaps 102: .Ss HTML Filter
103: The HTML filter, specified by
104: .Fl f Ar html ,
105: accepts the following filter-specific arguments:
106: .Bl -tag -width "\-c css"
107: .It Fl c Ar css
108: The CSS file location, which defaults to
109: .Ar mdocml.css .
110: .It Fl e
111: Whether to embed the CSS file into the HTML prologue.
112: .El
1.26 ! kristaps 113: .Pp
! 114: By default, the HTML filter produces HTML-4.01 strict mark-up. The
! 115: default CSS document styles the page as it would appear in a terminal
! 116: window.
1.18 kristaps 117: .\"
1.17 kristaps 118: .Sh EXAMPLES
119: To produce an HTML4-strict document
120: .Pa mdocml.html
121: for
122: .Pa mdocml.1
123: with the default, embedded style-sheet:
124: .Pp
1.18 kristaps 125: .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
1.17 kristaps 126: .Pp
127: To create an XML document on standard output from
128: .Pa mdocml.1
129: with the default namespace identifiers
130: .Li head ,
131: .Li body ,
132: .Li block
133: and
134: .Li inline :
135: .Pp
1.26 ! kristaps 136: .D1 % mdocml -Wall,error -fxml mdocml.1
! 137: .Pp
! 138: The previous example will also halt on input document warnings.
1.12 kristaps 139: .\"
1.3 kristaps 140: .Sh SEE ALSO
141: .Xr groff 1 ,
142: .Xr mdoc.samples 7 ,
143: .Xr mdoc 7
1.1 kristaps 144: .\" .Sh STANDARDS
145: .\" .Sh HISTORY
1.3 kristaps 146: .Sh AUTHORS
147: The
148: .Nm
149: utility was written by
1.22 kristaps 150: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.3 kristaps 151: .\"
152: .Sh CAVEATS
1.7 kristaps 153: Most caveats of
1.3 kristaps 154: .Nm
1.7 kristaps 155: stem from ambiguities in
156: .Xr mdoc 7
157: or the necessary limitations of converting an ad hoc language into
158: structured ones:
159: .Bl -enum -compact -offset indent
160: .It
1.12 kristaps 161: The engine doesn't understand the
162: .Sq \&No ,
163: .Sq \&Db ,
164: .Sq \&Xc ,
165: and
1.3 kristaps 166: .Sq \&Xo
1.12 kristaps 167: mdoc macros.
1.7 kristaps 168: .It
169: All macro arguments may be quoted, instead of only some.
170: .It
1.12 kristaps 171: Blank lines raise errors.
1.7 kristaps 172: .It
1.9 kristaps 173: If terminating punctuation is found, then
174: .Em all
175: remaining tokens are flushed after line scope is closed, not just the
176: last one.
1.7 kristaps 177: .El
1.14 kristaps 178: .Pp
179: The roff engine in
180: .Nm
181: produces text in-line; thus, output may already be partially written by
182: the time an error is encountered.
1.1 kristaps 183: .\" .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