Return to mdocml.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdocml.1, Revision 1.10

1.1       kristaps    1: .\"    $OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
                      2: .\"
                      3: .\" The following requests are required for all man pages.
                      4: .\"
                      5: .\" Remove `\&' from the line below.
1.2       kristaps    6: .Dd $Mdocdate$
                      7: .Dt mdocml 1
1.1       kristaps    8: .Os
1.3       kristaps    9: .\"
1.1       kristaps   10: .Sh NAME
1.2       kristaps   11: .Nm mdocml
                     12: .Nd compile manpage source into mark-up language
1.3       kristaps   13: .\"
1.1       kristaps   14: .Sh SYNOPSIS
1.2       kristaps   15: .Nm mdocml
1.10    ! kristaps   16: .Op Fl W
1.7       kristaps   17: .Op Fl f Ar filter
1.2       kristaps   18: .Op Fl o Ar outfile
                     19: .Op Ar infile
1.3       kristaps   20: .\"
1.1       kristaps   21: .Sh DESCRIPTION
                     22: The
                     23: .Nm
1.7       kristaps   24: utility parses
                     25: .Xr mdoc
                     26: formatted manual source and passes results into the output filter
                     27: dictated by
                     28: .Fl f Ar filter .
                     29: The only current output filter is
1.10    ! kristaps   30: .Ar xml ,
1.7       kristaps   31: the default.  The arguments are as follows:
1.10    ! kristaps   32: .Bl -tag -width "\-o outfile"
        !            33: .It Fl f Ar filter
        !            34: The output filter name, which defaults to
        !            35: .Ar xml .
        !            36: .It Fl o Ar outfile
1.2       kristaps   37: Place output in
                     38: .Ar outfile ,
                     39: which may be
1.6       kristaps   40: .Qq \-
1.10    ! kristaps   41: for stdout.  The default is stdout.
        !            42: .It Fl W
        !            43: Print compiler warnings to stderr.
1.2       kristaps   44: .It Ar infile
                     45: Read input from
                     46: .Ar infile ,
                     47: which may be
1.6       kristaps   48: .Qq \-
1.10    ! kristaps   49: for stdin.  The default is stdin.
1.2       kristaps   50: .El
1.10    ! kristaps   51: .Ss XML Filter
        !            52: The XML filter, specified by
        !            53: .Fl f Ar xml ,
        !            54: is the default filter.  It creates an XML document where element names are
        !            55: their respective roff macro names.  Each element name has an associated
        !            56: namespace, which is one of
        !            57: .Qq block ,
        !            58: .Qq inline ,
        !            59: or
        !            60: .Qq special ,
        !            61: corresponding to the display mode of a node.
        !            62: .Pp
        !            63: Sample output follows:
        !            64: .Bd -literal
        !            65: <?xml version="1.0" encoding="UTF-8"?>
        !            66: <block:mdoc>
        !            67:   <block:Sh>
        !            68:     <inline:Sh>NAME</inline:Sh> <inline:Nm>example</inline:Nm>
        !            69:     <inline:Nd>example text</inline:Nd>
        !            70:   </block:Sh>
        !            71: </block:mdoc>
        !            72: .Ed
1.1       kristaps   73: .\" The following requests should be uncommented and used where appropriate.
                     74: .\" This next request is for sections 2, 3, and 9 function return values only.
                     75: .\" .Sh RETURN VALUES
                     76: .\" This next request is for sections 1, 6, 7 & 8 only.
                     77: .\" .Sh ENVIRONMENT
                     78: .\" .Sh FILES
                     79: .\" .Sh EXAMPLES
                     80: .\" This next request is for sections 1, 4, 6, and 8 only.
                     81: .\" .Sh DIAGNOSTICS
                     82: .\" The next request is for sections 2, 3, and 9 error and signal handling only.
                     83: .\" .Sh ERRORS
1.3       kristaps   84: .Sh SEE ALSO
                     85: .Xr groff 1 ,
                     86: .Xr mdoc.samples 7 ,
                     87: .Xr mdoc 7
1.1       kristaps   88: .\" .Sh STANDARDS
                     89: .\" .Sh HISTORY
1.3       kristaps   90: .Sh AUTHORS
                     91: The
                     92: .Nm
                     93: utility was written by
1.9       kristaps   94: .An Em Kristaps Dzonsons Aq kristaps@kth.se .
1.3       kristaps   95: .\"
                     96: .Sh CAVEATS
1.7       kristaps   97: Most caveats of
1.3       kristaps   98: .Nm
1.7       kristaps   99: stem from ambiguities in
                    100: .Xr mdoc 7
                    101: or the necessary limitations of converting an ad hoc language into
                    102: structured ones:
                    103: .Bl -enum -compact -offset indent
                    104: .It
                    105: The engine doesn't understand
1.3       kristaps  106: .Sq \&Xo
                    107: and
                    108: .Sq \&Xc
                    109: troff macros.
1.7       kristaps  110: .It
                    111: All macro arguments may be quoted, instead of only some.
                    112: .It
                    113: Blank lines raise warnings.
                    114: .It
1.9       kristaps  115: If terminating punctuation is found, then
                    116: .Em all
                    117: remaining tokens are flushed after line scope is closed, not just the
                    118: last one.
1.7       kristaps  119: .El
1.1       kristaps  120: .\" .Sh BUGS