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
 .Os
 .\"
 .Sh NAME


@@ -9,7 +9,8 @@
 .\"
 .Sh SYNOPSIS
 .Nm mdocml
 .\"
 .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
 .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
 .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
 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
 .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
 .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 
 .It Ar infile
 Read input from
 .Ar infile ,
 which may be 

-.Qq \-
+.Dq \-

 for stdin.
 .El
 .Pp
 By default,
 .Nm
 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 ,
 .\"
 .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 
 .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
 or

-.Qq inline ,
+.Dq inline ,

 corresponding to the display mode of a node.  The document root is
 always the
 corresponding to the display mode of a node.  The document root is
 always the

-.Qq mdoc
+.Dq mdoc

 element, in the default namespace; the 
 element, in the default namespace; the 

-.Qq head
+.Dq head

 namespace is for block headers (such as 
 .Sq .Ss
 and
 .Sq .Sh ) ;
 the
 namespace is for block headers (such as 
 .Sq .Ss
 and
 .Sq .Sh ) ;
 the

-.Qq body
+.Dq body

 namespace is for block bodies; and the
 namespace is for block bodies; and the

-.Qq inline
+.Dq inline

 namespace is for in-line elements (such as
 .Sq .Em ) .
 namespace is for in-line elements (such as
 .Sq .Em ) .

+.\"

 .Ss HTML Filter
 The HTML filter, specified by
 .Fl f Ar html ,
 .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
 .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 
 .\" 
 .Sh EXAMPLES
 To produce an HTML4-strict document 


@@ -104,7 +133,9 @@ with the default namespace identifiers
 and
 .Li inline :
 .Pp
 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 ,
 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,


@@ -116,7 +147,7 @@ and
 The
 .Nm
 utility was written by 
 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
 .\"
 .Sh CAVEATS
 Most caveats of


@@ -128,8 +159,6 @@ structured ones:
 .Bl -enum -compact -offset indent
 .It 
 The engine doesn't understand the
 .Bl -enum -compact -offset indent
 .It 
 The engine doesn't understand the

-.Sq \&Xo ,
-.Sq \&Xc ,

 .Sq \&No ,
 .Sq \&Db ,
 .Sq \&Xc ,
 .Sq \&No ,
 .Sq \&Db ,
 .Sq \&Xc ,