Prologue Dd and Dt macros.

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index 62a2b0725227b0d445be4f205a9653b2bae0797f..6493e411582b239d1ae038cb5f901af8ecf8e573 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -1,6 +1,6 @@
 .\"
-.Dd $Mdocdate: December 5 2008 $
-.Dt mdocml 1 alpha
+.Dd $Mdocdate: December 10 2008 $
+.Dt mdocml 1
 .Os
 .\"
 .Sh NAME
@@ -9,7 +9,8 @@
 .\"
 .Sh SYNOPSIS
 .Nm mdocml
-.Op Fl vW
+.Op Fl v
+.Op Fl W Ns Ar err...
 .Op Fl f Ar filter
 .Op Fl o Ar outfile
 .Op Ar infile
@@ -19,61 +20,85 @@ The
 .Nm
 utility parses mdoc formatted manual source and passes results into an
 output filter.  The current output filters are
-.Ar html
+.Fl f Ar html
 and
-.Ar xml ,
-the default.  Arguments common to all filters follow:
+.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.
+The output filter name.  
 .It Fl o Ar outfile
 Write output to 
 .Ar outfile ,
 which may be
-.Qq \-
-for stdout.
-.It Fl W
-Print warnings to stderr.
+.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 \-
+.Dq \-
 for stdin.
 .El
 .Pp
 By default,
 .Nm
-reads from stdin and writes to stdout using the xml filter.
+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 ,
-is the default filter.  This filter has no additional arguments.
+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 
-.Qq block ,
-.Qq head ,
-.Qq body ,
+.Dq block ,
+.Dq head ,
+.Dq body ,
 or
-.Qq inline ,
+.Dq inline ,
 corresponding to the display mode of a node.  The document root is
 always the
-.Qq mdoc
+.Dq mdoc
 element, in the default namespace; the 
-.Qq head
+.Dq head
 namespace is for block headers (such as 
 .Sq .Ss
 and
 .Sq .Sh ) ;
 the
-.Qq body
+.Dq body
 namespace is for block bodies; and the
-.Qq inline
+.Dq inline
 namespace is for in-line elements (such as
 .Sq .Em ) .
+.\"
 .Ss HTML Filter
 The HTML filter, specified by
 .Fl f Ar html ,
@@ -85,6 +110,10 @@ The CSS file location, which defaults to
 .It Fl e
 Whether to embed the CSS file into the HTML prologue.
 .El
+.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 
@@ -104,7 +133,9 @@ with the default namespace identifiers
 and
 .Li inline :
 .Pp
-.D1 % mdocml mdocml.1 
+.D1 % mdocml -Wall,error -fxml mdocml.1 
+.Pp
+The previous example will also halt on input document warnings.
 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,
@@ -116,7 +147,7 @@ and
 The
 .Nm
 utility was written by 
-.An Em Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
 .\"
 .Sh CAVEATS
 Most caveats of
@@ -128,8 +159,6 @@ structured ones:
 .Bl -enum -compact -offset indent
 .It 
 The engine doesn't understand the
-.Sq \&Xo ,
-.Sq \&Xc ,
 .Sq \&No ,
 .Sq \&Db ,
 .Sq \&Xc ,