===================================================================
RCS file: /cvs/mandoc/Attic/mdocterm.1,v
retrieving revision 1.10
retrieving revision 1.25
diff -u -p -r1.10 -r1.25
--- mandoc/Attic/mdocterm.1	2009/03/03 21:07:01	1.10
+++ mandoc/Attic/mdocterm.1	2009/03/17 00:40:17	1.25
@@ -1,6 +1,6 @@
-.\" $Id: mdocterm.1,v 1.10 2009/03/03 21:07:01 kristaps Exp $
+.\" $Id: mdocterm.1,v 1.25 2009/03/17 00:40:17 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,29 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 3 2009 $
-.Dt mdocmterm 1
+.Dd $Mdocdate: March 17 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 vV
+.Op Fl f Ns Ar option...
+.Op Fl O Ns Ar option...
 .Op Fl W Ns Ar err...
 .Op Ar infile
+.Nm mdocterm
+.Op Fl hi
+.Op Fl m Ns Ar name
+.Op Fl n Ns Ar num
+.Op Fl o Ns Ar list
+.Op Fl r Ns Ar cn
+.Op Fl T Ns Ar name
+.Op Ar infile
 .\" SECTION
 .Sh DESCRIPTION
 The
@@ -36,11 +46,24 @@ 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.
 .\" ITEM
+.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 O Ns Ar option...
+Front-end options.  See
+.Sx Front-end Options
+for details.
+.\" ITEM
 .It Fl W Ns Ar err...
 Print warning messages.  May be set to 
 .Fl W Ns Ar all
@@ -65,6 +88,15 @@ for stdin.
 .El
 .\" PARAGRAPH
 .Pp
+If
+.Xr nroff 1
+arguments are supplied on the command line
+.Pq Fl himnorT ,
+these are ignored unless 
+.Xr nroff 1
+is invoked on parse failure.
+.\" PARAGRAPH
+.Pp
 The
 .Nm
 utility is a formatting front-end for
@@ -75,157 +107,95 @@ 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.  If
+.Ar infile
+can't be parsed (isn't valid mdoc, doesn't contain valid syntax, etc.),
+.Xr nroff 1
+is invoked.  If no 
+.Xr nroff 1
+command-line argumnets aren't provided,
+.Fl m Ns Ar andoc
+is implied.
 .\" PARAGRAPH
 .Pp
-.Ex -std mdocmterm
-.\" PARAGRAPH
-.Pp
-.Nm
-is
-.Ud
+.Ex -std mdocterm
 .\" SUB-SECTION
-.Ss Character Escapes
-This section documents the character-escapes accepted by
-.Xr mdocterm 1 .
-Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
-\\*[n] and \\*x forms described in
-.Xr mdoc.samples 7
-are deprecated, but still rendered.  All one- and two-character
-sequences may be used in the n-character sequence \\[n].
-.Pp
-Note that the
-.Em Output
-column will render differently whether executed with
-.Xr mdocterm 1 
-or another output filter.
-.\" PARAGRAPH
-.Pp
-Grammatic:
-.Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(em
-\\(em (em-dash)
-.It \(en
-\\(en (en-dash)
-.It \-
-\\- (hyphen)
-.It \\
-\\ (back-slash)
+.Ss Front-end Options
+The default behaviour may be overriden with the
+.Fl O
+flag.  The available options are as follows:
+.Bl -tag -width XXXXXXXXXXXX -offset XXXX
+.It Fl O Ns Ar nopunt
+Don't punt to 
+.Xr nroff 1
+if 
+.Ar infile
+may not be parsed.
 .El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(rB
-\\(rB (right bracket)
-.It \(lB
-\\(rB (left bracket)
-.It \(lq
-\\(lq (left double-quote)
-.It \(rq
-\\(rq, \\' (right double-quote)
-.It \(oq
-\\(lq, \\` (left single-quote)
-.It \(aq
-\\(aq (right single-quote, apostrophe)
+.\" 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
-Indicatives:
+As with the
+.Fl W
+flag, multiple
+.Fl f
+and
+.Fl O
+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
+utility correctly renders all 
+.Sx Special Characters
+in
+.Xr mdoc 7
+in 7-bit ASCII.
 .Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(<-
-\\(<- (left arrow)
-.It \(->
-\\(-> (right arrow)
-.It \(ua
-\\(ua (up arrow)
-.It \(da
-\\(da (down arrow)
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(<=
-\\(<= (less-than-equal)
-.It \(>=
-\\(>= (greater-than-equal)
-.It \(==
-\\(== (greater-than-equal)
-.It \(!=
-\\(!= (not equal)
-.It \(if
-\\(if (infinity)
-.It \(na
-\\(na (NaN)*
-.It \(+-
-\\(+- (plus-minus)
-.It \(**
-\\(** (asterisk)
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics:
-.Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(ga
-\\(ga (accent grave)
-.It \(aa
-\\(aa (accent accute)
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Pp
-.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
-.It Em Output
-.Em Input (Name)
-.It \(bu
-\\(bu (bullet)
-.It \(ba
-\\(ba (bar)
-.It \(co
-\\(co (copyright)
-.El 
-.Pp
-*This is a deviation from the standard, as NaN is usually rendered as
-\\*(Na, which is a deprecated form.  We introduce \\(na, which follows
-the more general syntax.
+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 -R
+.D1 % mdocterm mdocterm.1 | less
 .\" SECTION
 .Sh SEE ALSO
 .Xr mdoctree 1 ,
 .Xr mdoclint 1 ,
-.Xr mdoc.samples 7 ,
 .Xr mdoc 7 ,
 .Xr mdoc 3
 .\" 
@@ -233,7 +203,7 @@ To pipe a manual page to the pager:
 The
 .Nm
 utility was written by 
-.An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@openbsd.org .
 .\" SECTION
 .Sh CAVEATS
 See
@@ -247,9 +217,9 @@ utility doesn't yet know how to display the following:
 .Pp
 .Bl -bullet -compact
 .It
-Only \-bullet , \-dash , \-enum , \-hyphen , \-tag and \-ohang
+The \-hang 
 .Sq \&Bl
-lists are supported.
+list is not yet supported.
 .It
 The \-literal and \-unfilled 
 .Sq \&Bd
@@ -258,4 +228,8 @@ displays only accept text contents.
 The
 .Sq \&Xo/Xc
 pair isn't supported (and never will be).
+.It
+The
+.Sq \&Sm
+macro has no effect, yet.
 .El