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