===================================================================
RCS file: /cvs/mandoc/Attic/mdocml.1,v
retrieving revision 1.1
retrieving revision 1.29
diff -u -p -r1.1 -r1.29
--- mandoc/Attic/mdocml.1	2008/11/22 14:53:29	1.1
+++ mandoc/Attic/mdocml.1	2009/01/20 13:44:05	1.29
@@ -1,40 +1,96 @@
-.\"	$OpenBSD: mdocml.1,v 1.1 2008/11/22 14:53:29 kristaps Exp $
 .\"
-.\" The following requests are required for all man pages.
-.\"
-.\" Remove `\&' from the line below.
-.Dd $\&Mdocdate$
-.Dt NAME SECTION#
+.Dd $Mdocdate: January 20 2009 $
+.Dt mdocml 1
 .Os
+.\"
 .Sh NAME
-.Nm program
-.Nd one line about what it does
+.Nm mdocml
+.Nd mdoc macro compiler
+.\"
 .Sh SYNOPSIS
-.\" For a program:  program [-abc] file ...
-.Nm program
-.Op Fl abc
-.Ar
+.Nm mdocml
+.Op Fl v
+.Op Fl W Ns Ar err...
+.Op Ar infile
+.\"
 .Sh DESCRIPTION
 The
 .Nm
-utility processes files ...
-something
-something.
-.\" 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
-.\" .Sh SEE ALSO
-.\" .Xr foobar 1
+utility interfaces the
+.Xr mdoc 3
+library to scan, parse and validate mdoc-macro documents.  Arguments
+follow:
+.Bl -tag -width "\-Werr... "
+.It Fl W Ns Ar err...
+Print warning messages.  May be set to 
+.Fl W Ns Ar all
+for all warnings, 
+.Ar compat
+for groff/troff-compatibility warnings, or
+.Ar syntax
+for syntax warnings.  If
+.Fl W Ns Ar error 
+is specified, 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
+Print verbose parsing output.
+.It Ar infile
+Read input from
+.Ar infile ,
+which may be 
+.Dq \-
+for stdin.
+.El
+.Pp
+Parsing and validation rules are drawn entirely from the 
+.Xr mdoc 7
+and
+.Xr mdoc.samples 7 
+manuals.
+.Pp
+By default,
+.Nm
+reads from stdin, writes messages to stdout, and writes errors and
+warnings to stderr.
+.Pp
+.Ex -std mdocml
+.Pp
+.Nm
+is
+.Ud
+.\" 
+.Sh EXAMPLES
+To validate this manual page:
+.Pp
+.D1 % mdocml \-Wall,error mdocml.1 
+.\"
+.Sh SEE ALSO
+.Xr groff 1 ,
+.Xr mdoc.samples 7 ,
+.Xr mdoc 7 ,
+.Xr mdoc 3
 .\" .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
+The most glaring short-coming of 
+.Nm
+is that it doesn't yet support the 
+.Sq \&Xc
+and
+.Sq \&Xo
+macros when used to extend the line arguments to
+.Sq \&It ;
+in effect, trampling the body section.  We note that this is explicitly
+discouraged in
+.Xr mdoc.samples 7 ,
+but in practice used quite often.
 .\" .Sh BUGS