version 1.4, 2009/02/25 13:30:53 |
version 1.26, 2009/03/19 11:49:00 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the |
.\" purpose with or without fee is hereby granted, provided that the |
|
|
.\" 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 V |
|
.Op Fl f Ns Ar option... |
.Op Fl W Ns Ar err... |
.Op Fl W Ns Ar err... |
.Op Ar infile |
.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 version and exit. |
.\" ITEM |
.\" ITEM |
|
.It Fl f Ns Ar option... |
|
Override default compiler behaviour. See |
|
.Sx Compiler 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 |
Line 56 termination. Multiple |
|
Line 62 termination. Multiple |
|
arguments may be comma-separated, such as |
arguments may be comma-separated, such as |
.Fl W Ns Ar error,all . |
.Fl W Ns Ar error,all . |
.\" ITEM |
.\" ITEM |
.It Ar infile |
.It Ar infile... |
Read input from |
Read input from zero or more |
.Ar infile , |
.Ar infile . |
which may be |
If unspecified, reads from stdin. |
.Dq \- |
|
for stdin. |
|
.El |
.El |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
Line 75 input, documented at |
|
Line 79 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. |
.\" PARAGRAPH |
.\" PARAGRAPH |
.Pp |
.Pp |
.Ex -std mdocmterm |
.Ex -std mdocterm |
|
.\" 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 |
|
As with the |
|
.Fl W |
|
flag, multiple |
|
.Fl f |
|
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 |
.Nm |
is |
utility correctly renders all |
.Ud |
.Sx Special Characters |
|
in |
|
.Xr mdoc 7 |
|
in 7-bit ASCII. |
|
.Pp |
|
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 |
.\" SECTION |
.Sh EXAMPLES |
.Sh EXAMPLES |
To display this manual page: |
To display this manual page: |
.\" 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 mdoclint 1 , |
|
.Xr mdoc.samples 7 , |
|
.Xr mdoc 7 , |
.Xr mdoc 7 , |
.Xr mdoc 3 |
.Xr mdoc 3 |
.\" |
.\" |
Line 112 To pipe a manual page to the pager: |
|
Line 150 To pipe a manual page to the pager: |
|
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons Aq kristaps@kth.se . |
.An Kristaps Dzonsons Aq kristaps@openbsd.org . |
.\" SECTION |
.\" SECTION |
.Sh CAVEATS |
.Sh CAVEATS |
See |
See |
.Xr mdoc 3 |
.Xr mdoc 3 |
for a list of bugs, caveats, and incomplete macros regarding the |
for a list of bugs, caveats, and incomplete macros regarding the |
document parse. |
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 |