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