*** empty log message ***

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index 00a600dac1ef2e2bef69dd28acdcea9127389875..db7e4caeec1475a4e35896b60bafaff57b91c1a9 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -1,6 +1,6 @@
 .\"
 .\"

-.Dd $Mdocdate: December 3 2008 $
-.Dt mdocml 1
+.Dd $Mdocdate: December 9 2008 $
+.Dt mdocml 1 alpha

 .Os
 .\"
 .Sh NAME
 .Os
 .\"
 .Sh NAME


@@ -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


@@ -18,9 +19,11 @@
 The
 .Nm
 utility parses mdoc formatted manual source and passes results into an
 The
 .Nm
 utility parses mdoc formatted manual source and passes results into an

-output filter.  The only current output filter is
+output filter.  The current output filters are
+.Ar html
+and

 .Ar xml ,
 .Ar xml ,

-the default.  The arguments are as follows:
+the default.  Arguments common to all filters follow:

 .Bl -tag -width "\-o outfile"
 .It Fl f Ar filter
 The output filter name.
 .Bl -tag -width "\-o outfile"
 .It Fl f Ar filter
 The output filter name.


@@ -28,39 +31,92 @@ The output filter name.
 Write output to 
 .Ar outfile ,
 which may be
 Write output to 
 .Ar outfile ,
 which may be

-.Qq \-
+.Dq \-

 for stdout.
 for stdout.

-.It Fl W
-Print warnings to stderr.
+.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
 reads from stdin and writes to stdout using the xml filter.
 for stdin.
 .El
 .Pp
 By default,
 .Nm
 reads from stdin and writes to stdout using the xml filter.

+.Pp
+.Ex -std mdocml

 .\"
 .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
+is the default filter.  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 ,
-.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
-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
+.\" 
+.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 mdocml.1 

 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,
 .\"
 .Sh SEE ALSO
 .Xr groff 1 ,


@@ -72,7 +128,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,8 +140,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 ,