Return to mdocml.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdocml.1, Revision 1.16

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.16    ! kristaps   53: .Qq block ,
        !            54: .Qq head ,
        !            55: .Qq body ,
1.12      kristaps   56: or
1.10      kristaps   57: .Qq inline ,
1.12      kristaps   58: corresponding to the display mode of a node.  The document root is
                     59: always the
                     60: .Qq mdoc
                     61: element, in the default namespace.
1.1       kristaps   62: .\" This next request is for sections 1, 6, 7 & 8 only.
                     63: .\" .Sh ENVIRONMENT
1.12      kristaps   64: .\"
1.3       kristaps   65: .Sh SEE ALSO
                     66: .Xr groff 1 ,
                     67: .Xr mdoc.samples 7 ,
                     68: .Xr mdoc 7
1.1       kristaps   69: .\" .Sh STANDARDS
                     70: .\" .Sh HISTORY
1.3       kristaps   71: .Sh AUTHORS
                     72: The
                     73: .Nm
                     74: utility was written by
1.9       kristaps   75: .An Em Kristaps Dzonsons Aq kristaps@kth.se .
1.3       kristaps   76: .\"
                     77: .Sh CAVEATS
1.7       kristaps   78: Most caveats of
1.3       kristaps   79: .Nm
1.7       kristaps   80: stem from ambiguities in
                     81: .Xr mdoc 7
                     82: or the necessary limitations of converting an ad hoc language into
                     83: structured ones:
                     84: .Bl -enum -compact -offset indent
                     85: .It
1.12      kristaps   86: The engine doesn't understand the
                     87: .Sq \&Xo ,
                     88: .Sq \&Xc ,
                     89: .Sq \&No ,
                     90: .Sq \&Db ,
                     91: .Sq \&Xc ,
                     92: and
1.3       kristaps   93: .Sq \&Xo
1.12      kristaps   94: mdoc macros.
1.7       kristaps   95: .It
                     96: All macro arguments may be quoted, instead of only some.
                     97: .It
1.12      kristaps   98: Blank lines raise errors.
1.7       kristaps   99: .It
1.9       kristaps  100: If terminating punctuation is found, then
                    101: .Em all
                    102: remaining tokens are flushed after line scope is closed, not just the
                    103: last one.
1.7       kristaps  104: .El
1.14      kristaps  105: .Pp
                    106: The roff engine in
                    107: .Nm
                    108: produces text in-line; thus, output may already be partially written by
                    109: the time an error is encountered.
1.1       kristaps  110: .\" .Sh BUGS