-.\" $OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
.\"
-.\" The following requests are required for all man pages.
-.\"
-.\" Remove `\&' from the line below.
-.Dd $Mdocdate: November 25 2008 $
+.Dd $Mdocdate: December 10 2008 $
.Dt mdocml 1
.Os
.\"
.\"
.Sh SYNOPSIS
.Nm mdocml
+.Op Fl v
+.Op Fl W Ns Ar err...
+.Op Fl f Ar filter
.Op Fl o Ar outfile
.Op Ar infile
.\"
.Sh DESCRIPTION
The
.Nm
-utility compiles manpage source into a mark-up language. Its arguments
-are as follows:
-.Bl -tag -width "-o outfile"
+utility parses mdoc formatted manual source and passes results into an
+output filter. The current output filters are
+.Fl f Ar html
+and
+.Fl f Ar xml .
+By default,
+.Nm
+only validates its input. This may be explicitly directed with
+.Fl f Ar noop .
+Arguments common to all filters follow:
+.Bl -tag -width "\-o outfile"
+.It Fl f Ar filter
+The output filter name.
.It Fl o Ar outfile
-Place output in
+Write output to
.Ar outfile ,
which may be
-.Qq -
-for standard output. The default is standard output.
+.Dq \-
+for stdout. This is meaningless for
+.Fl f Ar noop .
+.It Fl W Ns Ar err...
+Print warning messages. If set to
+.Fl W Ns Ar all ,
+all warnings are printed; if
+.Fl W Ns Ar error ,
+warnings are considered errors and cause utility termination. Multiple
+.Fl W
+arguments may be comma-separated, such as
+.Fl W Ns Ar error,all .
+.It Fl v
+Make warning and error messages verbose.
.It Ar infile
Read input from
.Ar infile ,
which may be
-.Qq -
-for standard input. The default is standard input.
+.Dq \-
+for stdin.
+.El
+.Pp
+By default,
+.Nm
+reads from stdin and writes to stdout.
+.Pp
+.Ex -std mdocml
+.\"
+.Ss Noop Filter
+The default noop
+.Dq validating
+filter simply validates its input; it produces no output beyond error
+and warning messages.
+.\"
+.Ss XML Filter
+The XML filter, specified by
+.Fl f Ar xml ,
+produces correctly-formatted XML output. This filter has no additional
+arguments.
+.Pp
+The XML filter creates an XML document where element names are their respective
+roff macro names. Each element name has an associated
+namespace, which is one of
+.Dq block ,
+.Dq head ,
+.Dq body ,
+or
+.Dq inline ,
+corresponding to the display mode of a node. The document root is
+always the
+.Dq mdoc
+element, in the default namespace; the
+.Dq head
+namespace is for block headers (such as
+.Sq .Ss
+and
+.Sq .Sh ) ;
+the
+.Dq body
+namespace is for block bodies; and the
+.Dq inline
+namespace is for in-line elements (such as
+.Sq .Em ) .
+.\"
+.Ss HTML Filter
+The HTML filter, specified by
+.Fl f Ar html ,
+accepts the following filter-specific arguments:
+.Bl -tag -width "\-c css"
+.It Fl c Ar css
+The CSS file location, which defaults to
+.Ar mdocml.css .
+.It Fl e
+Whether to embed the CSS file into the HTML prologue.
.El
-.\" The following requests should be uncommented and used where appropriate.
-.\" This next request is for sections 2, 3, and 9 function return values only.
-.\" .Sh RETURN VALUES
-.\" This next request is for sections 1, 6, 7 & 8 only.
-.\" .Sh ENVIRONMENT
-.\" .Sh FILES
-.\" .Sh EXAMPLES
-.\" This next request is for sections 1, 4, 6, and 8 only.
-.\" .Sh DIAGNOSTICS
-.\" The next request is for sections 2, 3, and 9 error and signal handling only.
-.\" .Sh ERRORS
+.Pp
+By default, the HTML filter produces HTML-4.01 strict mark-up. The
+default CSS document styles the page as it would appear in a terminal
+window.
+.\"
+.Sh EXAMPLES
+To produce an HTML4-strict document
+.Pa mdocml.html
+for
+.Pa mdocml.1
+with the default, embedded style-sheet:
+.Pp
+.D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
+.Pp
+To create an XML document on standard output from
+.Pa mdocml.1
+with the default namespace identifiers
+.Li head ,
+.Li body ,
+.Li block
+and
+.Li inline :
+.Pp
+.D1 % mdocml -Wall,error -fxml mdocml.1
+.Pp
+The previous example will also halt on input document warnings.
+.\"
.Sh SEE ALSO
.Xr groff 1 ,
.Xr mdoc.samples 7 ,
.An Kristaps Dzonsons Aq kristaps@kth.se .
.\"
.Sh CAVEATS
-The
+Most caveats of
.Nm
-engine doesn't understand
-.Sq \&Xo
+stem from ambiguities in
+.Xr mdoc 7
+or the necessary limitations of converting an ad hoc language into
+structured ones:
+.Bl -enum -compact -offset indent
+.It
+The engine doesn't understand the
+.Sq \&No ,
+.Sq \&Db ,
+.Sq \&Xc ,
and
-.Sq \&Xc
-troff macros.
+.Sq \&Xo
+mdoc macros.
+.It
+All macro arguments may be quoted, instead of only some.
+.It
+Blank lines raise errors.
+.It
+If terminating punctuation is found, then
+.Em all
+remaining tokens are flushed after line scope is closed, not just the
+last one.
+.El
+.Pp
+The roff engine in
+.Nm
+produces text in-line; thus, output may already be partially written by
+the time an error is encountered.
.\" .Sh BUGS
git.ckatri.com / mandoc.git / blobdiff