mdoclint accepts multiple files

[mandoc.git] / mdocterm.1

diff --git a/mdocterm.1 b/mdocterm.1
index 3725440c6b3ba2e1a0e41277fc10af0f8697da29..96206bff402155845f5897bee7630863af79c3c2 100644 (file)
--- a/mdocterm.1
+++ b/mdocterm.1
@@ -1,4 +1,4 @@
-.\" $Id: mdocterm.1,v 1.15 2009/03/08 18:02:36 kristaps Exp $
+.\" $Id: mdocterm.1,v 1.21 2009/03/15 07:08:52 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -16,20 +16,29 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 8 2009 $
+.Dd $Mdocdate: March 15 2009 $
 .Dt mdocterm 1
 .Os
 .\" SECTION
 .Sh NAME
-.Nm mdocmterm
+.Nm mdocterm
 .Nd mdoc macro compiler
 .\" SECTION
 .Sh SYNOPSIS
-.Nm mdocmterm
+.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
@@ -50,6 +59,11 @@ Override default compiler behaviour.  See
 .Sx Compiler Options
 for details.
 .\" ITEM
+.It Fl O Ns Ar option...
+Terminal-encoding 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
@@ -74,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
@@ -85,16 +108,40 @@ input, documented at
 and
 .Xr mdoc.samples 7 ,
 into an abstract syntax tree.  
+.\" PARAGRAPH
 .Pp
 By default, 
 .Nm 
-reads from stdin and prints ANSI 
-.Qq raw
+reads from stdin and prints nroff 
+.Qq backspace
 terminal-encoded output to stdout, at this time to a fixed column with
-of 78 characters.
+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 Ar Ns andoc
+is implied.
 .\" PARAGRAPH
 .Pp
-.Ex -std mdocmterm
+.Ex -std mdocterm
+.\" SUB-SECTION
+.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.
+.It Fl O Ns Ar ansi
+Use ANSI/VT100 output encoding instead of backspaces.
+.El
 .\" SUB-SECTION
 .Ss Compiler Options
 Default compiler behaviour may be overriden with the
@@ -106,6 +153,8 @@ 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
@@ -113,19 +162,17 @@ 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
-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
+The following table shows all 
+.Xr mdoc 7
+character escapes rendered by
+.Nm .
 Note that the
 .Em Output
 column will render differently whether executed with
@@ -154,6 +201,10 @@ Enclosures:
 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 .It Em Output
 .Em Input (Name)
+.It \(rC
+\\(rC (right brace)
+.It \(lC
+\\(lC (left brace)
 .It \(ra
 \\(ra (right angle)
 .It \(la
@@ -162,6 +213,8 @@ Enclosures:
 \\(rB (right bracket)
 .It \(lB
 \\(lB (left bracket)
+.It \q
+\\q (double-quote)
 .It \(lq
 \\(lq (left double-quote)
 .It \(rq
@@ -243,20 +296,19 @@ Special symbols:
 the more general syntax.
 .\" SECTION
 .Sh EXAMPLES
-To display this manual page:
+To display this manual page on ANSI-capable terminal:
 .\" 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 2>&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
 .\" 
@@ -278,9 +330,9 @@ utility doesn't yet know how to display the following:
 .Pp
 .Bl -bullet -compact
 .It
-The \-hang and \-column
+The \-hang 
 .Sq \&Bl
-lists are not yet supported.
+list is not yet supported.
 .It
 The \-literal and \-unfilled 
 .Sq \&Bd