version 1.9, 2009/03/02 17:29:16 |
version 1.21, 2009/03/15 07:08:52 |
|
|
.\" PERFORMANCE OF THIS SOFTWARE. |
.\" PERFORMANCE OF THIS SOFTWARE. |
.\" |
.\" |
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt mdocmterm 1 |
.Dt mdocterm 1 |
.Os |
.Os |
.\" SECTION |
.\" SECTION |
.Sh NAME |
.Sh NAME |
.Nm mdocmterm |
.Nm mdocterm |
.Nd mdoc macro compiler |
.Nd mdoc macro compiler |
.\" SECTION |
.\" SECTION |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm mdocmterm |
.Nm mdocterm |
.Op Fl v |
.Op Fl vV |
|
.Op Fl f Ns Ar option... |
|
.Op Fl O Ns Ar option... |
.Op Fl W Ns Ar err... |
.Op Fl W Ns Ar err... |
.Op Ar infile |
.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 |
.\" SECTION |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
|
|
utility formats a BSD |
utility formats a BSD |
.Dq mdoc |
.Dq mdoc |
manual page for display on the terminal. The arguments are as follows: |
manual page for display on the terminal. The arguments are as follows: |
.Bl -tag -width "\-Werr... " |
.Bl -tag -width XXXXXXXXXXXX |
.\" ITEM |
.\" ITEM |
.It Fl v |
.It Fl v |
Print verbose parsing output. |
Print verbose parsing output. |
.\" ITEM |
.\" 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... |
.It Fl W Ns Ar err... |
Print warning messages. May be set to |
Print warning messages. May be set to |
.Fl W Ns Ar all |
.Fl W Ns Ar all |
|
|
.El |
.El |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.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 |
The |
.Nm |
.Nm |
utility is a formatting front-end for |
utility is a formatting front-end for |
Line 75 input, documented at |
|
Line 107 input, documented at |
|
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr mdoc.samples 7 , |
.Xr mdoc.samples 7 , |
into an abstract syntax tree. |
into an abstract syntax tree. |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
By default, |
By default, |
.Nm |
.Nm |
reads from stdin and prints terminal-encoded output to stdout. |
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 |
.\" PARAGRAPH |
.Pp |
.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 |
.\" PARAGRAPH |
.Pp |
.Pp |
.Nm |
As with the |
is |
.Fl W |
.Ud |
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 |
.\" SUB-SECTION |
.Ss Character Escapes |
.Ss Character Escapes |
This section documents the character-escapes accepted by |
The following table shows all |
.Xr mdocterm 1 . |
.Xr mdoc 7 |
Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx |
character escapes rendered by |
and \\*x forms described in |
.Nm . |
.Xr mdoc.samples 7 |
|
are deprecated, but still correctly rendered. For all two-character |
|
sequences, \\(xx is equivalent to the n-character \\[xx]. |
|
.Pp |
|
Note that the |
Note that the |
.Em Output |
.Em Output |
column will render differently whether executed with |
column will render differently whether executed with |
Line 106 column will render differently whether executed with |
|
Line 180 column will render differently whether executed with |
|
or another output filter. |
or another output filter. |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.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: |
Enclosures: |
.Pp |
.Pp |
.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact |
.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact |
.It Em Output |
.It Em Output |
.Em Input (Name) |
.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 |
.It \(rB |
\\(rB (right bracket) |
\\(rB (right bracket) |
.It \(lB |
.It \(lB |
\\(rB (left bracket) |
\\(lB (left bracket) |
|
.It \q |
|
\\q (double-quote) |
.It \(lq |
.It \(lq |
\\(lq (left double-quote) |
\\(lq (left double-quote) |
.It \(rq |
.It \(rq |
\\(rq (right double-quote) |
\\(rq (right double-quote) |
.It \(oq |
.It \(oq |
\\(lq (left single-quote) |
\\(oq, \\` (left single-quote) |
.It \(aq |
.It \(aq |
\\(aq (right single-quote, apostrophe) |
\\(aq, \\' (right single-quote, apostrophe) |
.El |
.El |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
|
|
.It \(>= |
.It \(>= |
\\(>= (greater-than-equal) |
\\(>= (greater-than-equal) |
.It \(== |
.It \(== |
\\(== (greater-than-equal) |
\\(== (equal) |
.It \(!= |
.It \(!= |
\\(!= (not equal) |
\\(!= (not equal) |
.It \(if |
.It \(if |
|
|
\\(na (NaN)* |
\\(na (NaN)* |
.It \(+- |
.It \(+- |
\\(+- (plus-minus) |
\\(+- (plus-minus) |
|
.It \(** |
|
\\(** (asterisk) |
.El |
.El |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.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. |
|
.Pp |
|
Diacritics: |
Diacritics: |
.Pp |
.Pp |
.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact |
.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact |
Line 189 Special symbols: |
|
Line 287 Special symbols: |
|
\\(bu (bullet) |
\\(bu (bullet) |
.It \(ba |
.It \(ba |
\\(ba (bar) |
\\(ba (bar) |
|
.It \(co |
|
\\(co (copyright) |
.El |
.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 |
.\" SECTION |
.Sh EXAMPLES |
.Sh EXAMPLES |
To display this manual page: |
To display this manual page on ANSI-capable terminal: |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
.D1 % mdocmterm \-Wall,error mdocmterm.1 |
.D1 % mdocterm \-Wall,error mdocterm.1 |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
To pipe a manual page to the pager: |
To pipe a manual page to the pager: |
.Pp |
.Pp |
.D1 % mdocterm mdocterm.1 | less -R |
.D1 % mdocterm mdocterm.1 | less |
.\" SECTION |
.\" SECTION |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mdoctree 1 , |
.Xr mdoctree 1 , |
.Xr mdoclint 1 , |
.Xr mdoclint 1 , |
.Xr mdoc.samples 7 , |
|
.Xr mdoc 7 , |
.Xr mdoc 7 , |
.Xr mdoc 3 |
.Xr mdoc 3 |
.\" |
.\" |
Line 227 utility doesn't yet know how to display the following: |
|
Line 330 utility doesn't yet know how to display the following: |
|
.Pp |
.Pp |
.Bl -bullet -compact |
.Bl -bullet -compact |
.It |
.It |
Only \-bullet , \-dash , \-enum , \-hyphen , \-tag and \-ohang |
The \-hang |
.Sq \&Bl |
.Sq \&Bl |
lists are supported. |
list is not yet supported. |
.It |
.It |
The \-literal and \-unfilled |
The \-literal and \-unfilled |
.Sq \&Bd |
.Sq \&Bd |
Line 238 displays only accept text contents. |
|
Line 341 displays only accept text contents. |
|
The |
The |
.Sq \&Xo/Xc |
.Sq \&Xo/Xc |
pair isn't supported (and never will be). |
pair isn't supported (and never will be). |
|
.It |
|
The |
|
.Sq \&Sm |
|
macro has no effect, yet. |
.El |
.El |