-.\" $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>
.\"
.\" 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
-.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
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...
+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
.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
.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 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
+.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
-.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
-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 | 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
.\"
.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
git.ckatri.com / mandoc.git / blobdiff