Prologue Dd and Dt macros.

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index df86183cad39a19e2723177fc5698a145667b21f..6493e411582b239d1ae038cb5f901af8ecf8e573 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -1,9 +1,5 @@
-.\"    $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 30 2008 $
+.Dd $Mdocdate: December 10 2008 $

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


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


@@ -21,55 +18,125 @@
 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm

-utility parses
-.Xr mdoc
-formatted manual source and passes results into the output filter
-dictated by 
-.Fl f Ar 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, which defaults to
-.Ar xml .
+The output filter name.  

 .It Fl o Ar outfile
 .It Fl o Ar outfile

-Place output in 
+Write output to 

 .Ar outfile ,
 which may be
 .Ar outfile ,
 which may be

-.Qq \-
-for stdout.  The default is stdout.
-.It Fl W
-Print compiler 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 \-
-for stdin.  The default is stdin.
+.Dq \-
+for stdin.

 .El
 .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 ,
 .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 ,
-.Qq inline ,
+.Dq block ,
+.Dq head ,
+.Dq body ,

 or
 or

-.Qq special ,
-corresponding to the display mode of a node.
-.\" 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
+.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
+.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 ,
 .Sh SEE ALSO
 .Xr groff 1 ,
 .Xr mdoc.samples 7 ,


@@ -80,7 +147,7 @@ corresponding to the display mode of a node.
 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


@@ -91,19 +158,26 @@ or the necessary limitations of converting an ad hoc language into
 structured ones:
 .Bl -enum -compact -offset indent
 .It 
 structured ones:
 .Bl -enum -compact -offset indent
 .It 

-The engine doesn't understand
-.Sq \&Xo
+The engine doesn't understand the
+.Sq \&No ,
+.Sq \&Db ,
+.Sq \&Xc ,

 and
 and

-.Sq \&Xc
-troff macros.
+.Sq \&Xo
+mdoc macros.

 .It 
 All macro arguments may be quoted, instead of only some.
 .It 
 .It 
 All macro arguments may be quoted, instead of only some.
 .It 

-Blank lines raise warnings.
+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
 .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
 .\" .Sh BUGS