Small fixes to output.

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index 205ad47ad6ccb45b901a11d58aba100794236339..df86183cad39a19e2723177fc5698a145667b21f 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -3,23 +3,62 @@
 .\" The following requests are required for all man pages.
 .\"
 .\" Remove `\&' from the line below.
-.Dd $\&Mdocdate$
-.Dt NAME SECTION#
+.Dd $Mdocdate: November 30 2008 $
+.Dt mdocml 1
 .Os
+.\"
 .Sh NAME
-.Nm program
-.Nd one line about what it does
+.Nm mdocml
+.Nd compile manpage source into mark-up language
+.\"
 .Sh SYNOPSIS
-.\" For a program:  program [-abc] file ...
-.Nm program
-.Op Fl abc
-.Ar
+.Nm mdocml
+.Op Fl W
+.Op Fl f Ar filter
+.Op Fl o Ar outfile
+.Op Ar infile
+.\"
 .Sh DESCRIPTION
 The
 .Nm
-utility processes files ...
-something
-something.
+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:
+.Bl -tag -width "\-o outfile"
+.It Fl f Ar filter
+The output filter name, which defaults to
+.Ar xml .
+.It Fl o Ar outfile
+Place output in 
+.Ar outfile ,
+which may be
+.Qq \-
+for stdout.  The default is stdout.
+.It Fl W
+Print compiler warnings to stderr.
+.It Ar infile
+Read input from
+.Ar infile ,
+which may be 
+.Qq \-
+for stdin.  The default is stdin.
+.El
+.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
+namespace, which is one of 
+.Qq block ,
+.Qq inline ,
+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
@@ -31,10 +70,40 @@ something.
 .\" .Sh DIAGNOSTICS
 .\" The next request is for sections 2, 3, and 9 error and signal handling only.
 .\" .Sh ERRORS
-.\" .Sh SEE ALSO
-.\" .Xr foobar 1
+.Sh SEE ALSO
+.Xr groff 1 ,
+.Xr mdoc.samples 7 ,
+.Xr mdoc 7
 .\" .Sh STANDARDS
 .\" .Sh HISTORY
-.\" .Sh AUTHORS
-.\" .Sh CAVEATS
+.Sh AUTHORS
+The
+.Nm
+utility was written by 
+.An Em Kristaps Dzonsons Aq kristaps@kth.se .
+.\"
+.Sh CAVEATS
+Most caveats of
+.Nm
+stem from ambiguities in 
+.Xr mdoc 7
+or the necessary limitations of converting an ad hoc language into
+structured ones:
+.Bl -enum -compact -offset indent
+.It 
+The engine doesn't understand
+.Sq \&Xo
+and
+.Sq \&Xc
+troff macros.
+.It 
+All macro arguments may be quoted, instead of only some.
+.It 
+Blank lines raise warnings.
+.It 
+If terminating punctuation is found, then 
+.Em all
+remaining tokens are flushed after line scope is closed, not just the
+last one.
+.El
 .\" .Sh BUGS