Prologue Dd and Dt macros.

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index b4a43518eecf00a2de8cd7ac2448dc62007fe108..6493e411582b239d1ae038cb5f901af8ecf8e573 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -1,5 +1,5 @@
 .\"
 .\"

-.Dd $Mdocdate: December 1 2008 $
+.Dd $Mdocdate: December 10 2008 $

 .Dt mdocml 1
 .Os
 .\"
 .Dt mdocml 1
 .Os
 .\"


@@ -9,7 +9,8 @@
 .\"
 .Sh SYNOPSIS
 .Nm mdocml
 .\"
 .Sh SYNOPSIS
 .Nm mdocml

-.Op Fl W
+.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


@@ -17,50 +18,124 @@
 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm

-utility parses
-.Xr mdoc
-formatted manual source and passes results into an output filter.  The
-only current output filter is
-.Ar xml ,
-the default.  The arguments are as follows:
+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
 .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.  It creates an XML document where element names are
-their respective roff macro names.  Each element name has an associated
+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 
 namespace, which is one of 

-.Qq block 
+.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
-element, in the default namespace.
-.\" This next request is for sections 1, 6, 7 & 8 only.
-.\" .Sh ENVIRONMENT
+.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
+.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 ,
 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,


@@ -72,7 +147,7 @@ element, in the default namespace.
 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


@@ -84,12 +159,8 @@ 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 \&Ns ,

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

-.Sq \&Sm ,

 .Sq \&Xc ,
 and
 .Sq \&Xo
 .Sq \&Xc ,
 and
 .Sq \&Xo


@@ -104,4 +175,9 @@ If terminating punctuation is found, then
 remaining tokens are flushed after line scope is closed, not just the
 last one.
 .El
 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
 .\" .Sh BUGS