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