mdoclint accepts multiple files

[mandoc.git] / mdocterm.1

diff --git a/mdocterm.1 b/mdocterm.1
index db9fccefc4b0d87cf1104305c8359cdbfb72b15f..96206bff402155845f5897bee7630863af79c3c2 100644 (file)
--- a/mdocterm.1
+++ b/mdocterm.1
@@ -1,4 +1,4 @@
-.\" $Id: mdocterm.1,v 1.4 2009/02/25 13:30:53 kristaps Exp $
+.\" $Id: mdocterm.1,v 1.21 2009/03/15 07:08:52 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"


@@ -16,19 +16,29 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: February 25 2009 $
-.Dt mdocmterm 1
+.Dd $Mdocdate: March 15 2009 $
+.Dt mdocterm 1

 .Os
 .\" SECTION
 .Sh NAME
 .Os
 .\" SECTION
 .Sh NAME

-.Nm mdocmterm
+.Nm mdocterm

 .Nd mdoc macro compiler
 .\" SECTION
 .Sh SYNOPSIS
 .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
 .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
 .\" 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:
 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
 .\" 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...
+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
 .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
 .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
 The
 .Nm
 utility is a formatting front-end for


@@ -75,36 +107,208 @@ input, documented at
 .Xr mdoc 7
 and
 .Xr mdoc.samples 7 ,
 .Xr mdoc 7
 and
 .Xr mdoc.samples 7 ,

-into an abstract syntax tree.
+into an abstract syntax tree.  

 .\" PARAGRAPH
 .Pp
 .\" 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 Ar Ns andoc
+is implied.

 .\" PARAGRAPH
 .Pp
 .\" 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
+.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
 .\" PARAGRAPH
 .Pp

-.Nm
-is
-.Ud
+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 following table shows all 
+.Xr mdoc 7
+character escapes rendered by
+.Nm .
+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)
+.El
+.\" PARAGRAPH
+.Pp
+Enclosures:
+.Pp
+.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
+\\(la (left angle)
+.It \(rB
+\\(rB (right bracket)
+.It \(lB
+\\(lB (left bracket)
+.It \q
+\\q (double-quote)
+.It \(lq
+\\(lq (left double-quote)
+.It \(rq
+\\(rq (right double-quote)
+.It \(oq
+\\(oq, \\` (left single-quote)
+.It \(aq
+\\(aq, \\' (right single-quote, apostrophe)
+.El
+.\" PARAGRAPH
+.Pp
+Indicatives:
+.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 \(==
+\\(== (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.

 .\" SECTION
 .Sh EXAMPLES
 .\" SECTION
 .Sh EXAMPLES

-To display this manual page:
+To display this manual page on ANSI-capable terminal:

 .\" PARAGRAPH
 .Pp
 .\" 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
 .\" 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 ,
 .\" SECTION
 .Sh SEE ALSO
 .Xr mdoctree 1 ,
 .Xr mdoclint 1 ,

-.Xr mdoc.samples 7 ,

 .Xr mdoc 7 ,
 .Xr mdoc 3
 .\" 
 .Xr mdoc 7 ,
 .Xr mdoc 3
 .\" 


@@ -119,3 +323,26 @@ See
 .Xr mdoc 3
 for a list of bugs, caveats, and incomplete macros regarding the
 document parse.
 .Xr mdoc 3
 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