Backed out PUNCT changes (again).

[mandoc.git] / mdocml.1

diff --git a/mdocml.1 b/mdocml.1
index ad46bba45808d75dc3c949bfe62838292769d42b..f40daf837ac120437aa4fb8490c2302c58a39e2d 100644 (file)
--- a/mdocml.1
+++ b/mdocml.1
@@ -3,35 +3,60 @@
 .\" The following requests are required for all man pages.
 .\"
 .\" Remove `\&' from the line below.
-.Dd $Mdocdate: November 22 2008 $
+.Dd $Mdocdate: November 30 2008 $
 .Dt mdocml 1
 .Os
+.\"
 .Sh NAME
 .Nm mdocml
 .Nd compile manpage source into mark-up language
+.\"
 .Sh SYNOPSIS
 .Nm mdocml
+.Op Fl vW
+.Op Fl f Ar filter
 .Op Fl o Ar outfile
 .Op Ar infile
+.\"
 .Sh DESCRIPTION
 The
 .Nm
-utility compiles manpage source into a mark-up language.  Its arguments
-are as follows:
-.Bl -tag -width "-o outfile"
-.It Fl o Ar outfile
+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 validate ,
+the default.  The arguments are as follows:
+.Bl -tag -width "\-o outfile,"
+.It Sq Fl o Ar outfile ,
 Place output in 
 .Ar outfile ,
 which may be
-.Qq -
+.Qq \-
 for standard output.  The default is standard output.
 .It Ar infile
 Read input from
 .Ar infile ,
 which may be 
-.Qq -
+.Qq \-
 for standard input.  The default is standard input.
+.It Fl v 
+Print messages (output depends on filter).
+.It Fl W
+Print warnings (output depends on filter).
 .El
+.Ss Validate Filter
+The validate filter, specified by
+.Fl f Ar validate ,
+is the default filter.  It produces no output, so specifying
+.Fl o Ar outfile
+results in an empty file.
+.Qq Op Op Fl a ) , Fl b ,
+.Bf Em
+.Qq Op Op Fl a ) , Fl b ,
+.Ef
 .\" 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
@@ -43,10 +68,37 @@ for standard input.  The default is standard input.
 .\" .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 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 
+Non-ascii characters may cause issues.
+.El
 .\" .Sh BUGS