===================================================================
RCS file: /cvs/mandoc/Attic/mdocterm.1,v
retrieving revision 1.1
retrieving revision 1.26
diff -u -p -r1.1 -r1.26
--- mandoc/Attic/mdocterm.1	2009/02/21 21:00:06	1.1
+++ mandoc/Attic/mdocterm.1	2009/03/19 11:49:00	1.26
@@ -1,6 +1,6 @@
-.\" $Id: mdocterm.1,v 1.1 2009/02/21 21:00:06 kristaps Exp $
+.\" $Id: mdocterm.1,v 1.26 2009/03/19 11:49:00 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the
@@ -16,19 +16,20 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: February 21 2009 $
-.Dt mdocmterm 1
+.Dd $Mdocdate: March 19 2009 $
+.Dt mdocterm 1
 .Os
 .\" SECTION
 .Sh NAME
-.Nm mdocmterm
+.Nm mdocterm
 .Nd mdoc macro compiler
 .\" SECTION
 .Sh SYNOPSIS
-.Nm mdocmterm
-.Op Fl v
+.Nm mdocterm
+.Op Fl V
+.Op Fl f Ns Ar option...
 .Op Fl W Ns Ar err...
-.Op Ar infile
+.Op Ar infile...
 .\" SECTION
 .Sh DESCRIPTION
 The
@@ -36,11 +37,16 @@ The
 utility formats a BSD 
 .Dq mdoc 
 manual page for display on the terminal.  The arguments are as follows:
-.Bl -tag -width "\-Werr... "
+.Bl -tag -width XXXXXXXXXXXX
 .\" ITEM
-.It Fl v
-Print verbose parsing output.
+.It Fl V
+Print version and exit.
 .\" ITEM
+.It Fl f Ns Ar option...
+Override default compiler behaviour.  See 
+.Sx Compiler Options
+for details.
+.\" ITEM
 .It Fl W Ns Ar err...
 Print warning messages.  May be set to 
 .Fl W Ns Ar all
@@ -56,14 +62,13 @@ termination.  Multiple 
 arguments may be comma-separated, such as
 .Fl W Ns Ar error,all .
 .\" ITEM
-.It Ar infile
-Read input from
-.Ar infile ,
-which may be 
-.Dq \-
-for stdin.
+.It Ar infile...
+Read input from zero or more
+.Ar infile .
+If unspecified, reads from stdin.
 .El
 .\" PARAGRAPH
+.Pp
 The
 .Nm
 utility is a formatting front-end for
@@ -74,30 +79,70 @@ input, documented at
 .Xr mdoc 7
 and
 .Xr mdoc.samples 7 ,
-into an abstract syntax tree.
+into an abstract syntax tree.  
 .\" PARAGRAPH
 .Pp
-By default,
-.Nm
-reads from stdin and prints terminal-encoded output to stdout.
+By default, 
+.Nm 
+reads from stdin and prints nroff 
+.Qq backspace
+terminal-encoded output to stdout, at this time to a fixed column with
+of 78 characters. 
 .\" PARAGRAPH
 .Pp
-.Ex -std mdocmterm
+.Ex -std mdocterm
+.\" SUB-SECTION
+.Ss Compiler Options
+Default compiler behaviour may be overriden with the
+.Fl f
+flag.  The available options are as follows:
+.Bl -tag -width XXXXXXXXXXXX -offset XXXX
+.It Fl f Ns Ar ign-scope
+When rewinding the scope of a block macro, forces the compiler to ignore
+scope violations.  This can seriously mangle the resulting tree.
+.It Fl f Ns Ar ign-escape
+Ignore invalid escape sequences.
+.It Fl f Ns Ar ign-macro
+Ignore unknown macros at the start of input lines.
+.El
 .\" PARAGRAPH
 .Pp
+As with the
+.Fl W
+flag, multiple
+.Fl f
+options may be grouped and delimited with a comma.  Using
+.Fl f Ns Ar ign-scope,ign-escape ,
+for example, will try to ignore scope and character-escape errors.
+.\" SUB-SECTION
+.Ss Character Escapes
+The
 .Nm
-is
-.Ud
+utility correctly renders all 
+.Sx Special Characters
+in
+.Xr mdoc 7
+in 7-bit ASCII.
+.Pp
+In the general sense, 
+.Nm
+will make a 
+.Pq best-effort
+to render complex characters; however, if a manual is using considerable
+special characters, some meaning may be lost in translation.
 .\" SECTION
 .Sh EXAMPLES
 To display this manual page:
 .\" PARAGRAPH
 .Pp
-.D1 % mdocmterm \-Wall,error mdocmterm.1 
+.D1 % mdocterm \-Wall,error mdocterm.1 
+.\" PARAGRAPH
+.Pp
+To pipe a manual page to the pager:
+.Pp
+.D1 % mdocterm mdocterm.1 | less
 .\" SECTION
 .Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoc.samples 7 ,
 .Xr mdoc 7 ,
 .Xr mdoc 3
 .\" 
@@ -105,9 +150,33 @@ To display this manual page:
 The
 .Nm
 utility was written by 
-.An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@openbsd.org .
 .\" SECTION
 .Sh CAVEATS
 See
 .Xr mdoc 3
-for a list of bugs, caveats, and incomplete macros.
+for a list of bugs, caveats, and incomplete macros regarding the
+document parse.
+.Pp
+The 
+.Nm
+utility doesn't yet know how to display the following:
+.Pp
+.Bl -bullet -compact
+.It
+The \-hang 
+.Sq \&Bl
+list is not yet supported.
+.It
+The \-literal and \-unfilled 
+.Sq \&Bd
+displays only accept text contents.
+.It
+The
+.Sq \&Xo/Xc
+pair isn't supported (and never will be).
+.It
+The
+.Sq \&Sm
+macro has no effect, yet.
+.El