Annotation of mandoc/mdocml.1, Revision 1.14
1.1 kristaps 1: .\"
1.2 kristaps 2: .Dd $Mdocdate$
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.10 kristaps 12: .Op Fl W
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
21: output filter. The only current output filter is
1.10 kristaps 22: .Ar xml ,
1.7 kristaps 23: the default. The arguments are as follows:
1.10 kristaps 24: .Bl -tag -width "\-o outfile"
25: .It Fl f Ar filter
1.12 kristaps 26: The output filter name.
1.10 kristaps 27: .It Fl o Ar outfile
1.12 kristaps 28: Write output to
1.2 kristaps 29: .Ar outfile ,
30: which may be
1.6 kristaps 31: .Qq \-
1.12 kristaps 32: for stdout.
1.10 kristaps 33: .It Fl W
1.12 kristaps 34: Print warnings to stderr.
1.2 kristaps 35: .It Ar infile
36: Read input from
37: .Ar infile ,
38: which may be
1.6 kristaps 39: .Qq \-
1.12 kristaps 40: for stdin.
1.2 kristaps 41: .El
1.12 kristaps 42: .Pp
43: By default,
44: .Nm
45: reads from stdin and writes to stdout using the xml filter.
46: .\"
1.10 kristaps 47: .Ss XML Filter
48: The XML filter, specified by
49: .Fl f Ar xml ,
50: is the default filter. It creates an XML document where element names are
51: their respective roff macro names. Each element name has an associated
52: namespace, which is one of
1.12 kristaps 53: .Qq block
54: or
1.10 kristaps 55: .Qq inline ,
1.12 kristaps 56: corresponding to the display mode of a node. The document root is
57: always the
58: .Qq mdoc
59: element, in the default namespace.
1.1 kristaps 60: .\" This next request is for sections 1, 6, 7 & 8 only.
61: .\" .Sh ENVIRONMENT
1.12 kristaps 62: .\"
1.3 kristaps 63: .Sh SEE ALSO
64: .Xr groff 1 ,
65: .Xr mdoc.samples 7 ,
66: .Xr mdoc 7
1.1 kristaps 67: .\" .Sh STANDARDS
68: .\" .Sh HISTORY
1.3 kristaps 69: .Sh AUTHORS
70: The
71: .Nm
72: utility was written by
1.9 kristaps 73: .An Em Kristaps Dzonsons Aq kristaps@kth.se .
1.3 kristaps 74: .\"
75: .Sh CAVEATS
1.7 kristaps 76: Most caveats of
1.3 kristaps 77: .Nm
1.7 kristaps 78: stem from ambiguities in
79: .Xr mdoc 7
80: or the necessary limitations of converting an ad hoc language into
81: structured ones:
82: .Bl -enum -compact -offset indent
83: .It
1.12 kristaps 84: The engine doesn't understand the
85: .Sq \&Xo ,
86: .Sq \&Xc ,
87: .Sq \&No ,
88: .Sq \&Db ,
89: .Sq \&Sm ,
90: .Sq \&Xc ,
91: and
1.3 kristaps 92: .Sq \&Xo
1.12 kristaps 93: mdoc macros.
1.7 kristaps 94: .It
95: All macro arguments may be quoted, instead of only some.
96: .It
1.12 kristaps 97: Blank lines raise errors.
1.7 kristaps 98: .It
1.9 kristaps 99: If terminating punctuation is found, then
100: .Em all
101: remaining tokens are flushed after line scope is closed, not just the
102: last one.
1.7 kristaps 103: .El
1.14 ! kristaps 104: .Pp
! 105: The roff engine in
! 106: .Nm
! 107: produces text in-line; thus, output may already be partially written by
! 108: the time an error is encountered.
1.1 kristaps 109: .\" .Sh BUGS
CVSweb