version 1.9, 2009/03/19 20:43:13 |
version 1.14, 2009/03/23 14:22:11 |
|
|
language is used to format |
language is used to format |
.Bx |
.Bx |
.Ux |
.Ux |
manuals. An |
manuals. In this reference document, we describe the syntax, ontology |
|
and structure of the |
.Nm |
.Nm |
|
language. |
|
.\" PARAGRAPH |
|
.Pp |
|
An |
|
.Nm |
document follows simple rules: lines beginning with the control |
document follows simple rules: lines beginning with the control |
character |
character |
.Sq \. |
.Sq \. |
are parsed for macros. Other lines are interpreted within the scope of |
are parsed for macros. Other lines are interpreted within the scope of |
prior macros. This document describes the encoding, ontology and syntax |
prior macros: |
of these macros. |
.Bd -literal -offset XXX |
|
\&.Sh Macro lines change control state. |
|
Other lines are interpreted within the current state. |
|
.Ed |
|
.\" PARAGRAPH |
|
.Pp |
|
Macros are two- or three-character sequences whose scope rules, rules |
|
that dictate handling of subsequent-line or same-line arguments, are |
|
governed by one of five classifications described in this document. |
.\" SECTION |
.\" SECTION |
.Sh CHARACTER ENCODING |
.Sh INPUT ENCODING |
.Nm |
.Nm |
documents may contain only printable characters, the space character |
documents may contain only graphable 7-bit ASCII characters, the space |
|
character |
.Sq \ , |
.Sq \ , |
and, in certain circumstances, the tab character |
and, in certain circumstances, the tab character |
.Sq \et . |
.Sq \et . |
All manuals must have |
All manuals must have |
.Sq \en |
.Sq \en |
line termination. |
line termination. |
|
.Pp |
|
The only time a blank line is acceptable is within |
|
the context of |
|
.Sq \&Bd \-literal |
|
or |
|
.Sq \&Bd \-unfilled . |
|
.Pp |
|
Tab characters |
|
.Pq \et |
|
are only acceptable when delimiting |
|
.Sq \&Bl \-column |
|
and in |
|
.Sq \&Bd \-literal |
|
or |
|
.Sq \&Bd \-unfilled |
|
contexts. |
.\" SUB-SECTION |
.\" SUB-SECTION |
.Ss Reserved Characters |
.Ss Reserved Characters |
Within a macro line, the following characters are reserved: |
Within a macro line, the following characters are reserved: |
Line 513 Special symbols: |
|
Line 544 Special symbols: |
|
.El |
.El |
.\" SECTION |
.\" SECTION |
.Sh ONTOLOGY |
.Sh ONTOLOGY |
Macros are classified in an ontology described by scope rules. |
Macros are classified in an ontology described by their scope rules. |
|
Some macros are allowed to deviate from their classifications to |
|
preserve backward-compatibility with old macro combinations still found |
|
in the manual corpus. These are specifically noted on a per-macro |
|
basis. |
.\" SUB-SECTION |
.\" SUB-SECTION |
.Ss Scope |
.Ss Scope |
.Bl -inset |
.Bl -inset |
Line 713 close at the invocation's end-of-line. |
|
Line 748 close at the invocation's end-of-line. |
|
.It \&.Dl Ta \&No Ta Yes |
.It \&.Dl Ta \&No Ta Yes |
.It \&.Ql Ta Yes Ta Yes |
.It \&.Ql Ta Yes Ta Yes |
.El |
.El |
|
.\" PARAGRAPH |
|
.Pp |
|
The |
|
.Sq \&Op |
|
may be broken by \&Oc as in the following example: |
|
.Bd -literal -offset XXXX |
|
\&.Oo |
|
\&.Op Fl a Oc |
|
.Ed |
|
.Pp |
|
In the above example, the scope of |
|
.Sq \&Op |
|
is technically broken by |
|
.Sq \&Oc , |
|
however, due to the overwhelming existence of this sequence, it's |
|
allowed. |
.\" SUB-SECTION |
.\" SUB-SECTION |
.Ss Block partial-explicit |
.Ss Block partial-explicit |
Each of these contains at least a body and, in limited circumstances, a |
Each of these contains at least a body and, in limited circumstances, a |
Line 766 then the macro accepts an arbitrary number of argument |
|
Line 817 then the macro accepts an arbitrary number of argument |
|
.It \&.Ar Ta Yes Ta Yes Ta n |
.It \&.Ar Ta Yes Ta Yes Ta n |
.It \&.Cd Ta Yes Ta \&No Ta >0 |
.It \&.Cd Ta Yes Ta \&No Ta >0 |
.It \&.Cm Ta Yes Ta Yes Ta n |
.It \&.Cm Ta Yes Ta Yes Ta n |
.It \&.Dv Ta Yes Ta Yes Ta >0 |
.It \&.Dv Ta Yes Ta Yes Ta n |
.It \&.Er Ta Yes Ta Yes Ta >0 |
.It \&.Er Ta Yes Ta Yes Ta >0 |
.It \&.Ev Ta Yes Ta Yes Ta >0 |
.It \&.Ev Ta Yes Ta Yes Ta n |
.It \&.Ex Ta \&No Ta \&No Ta 0 |
.It \&.Ex Ta \&No Ta \&No Ta 0 |
.It \&.Fa Ta Yes Ta Yes Ta >0 |
.It \&.Fa Ta Yes Ta Yes Ta n |
.It \&.Fd Ta \&No Ta \&No Ta >0 |
.It \&.Fd Ta \&No Ta \&No Ta >0 |
.It \&.Fl Ta Yes Ta Yes Ta n |
.It \&.Fl Ta Yes Ta Yes Ta n |
.It \&.Fn Ta Yes Ta Yes Ta >0 |
.It \&.Fn Ta Yes Ta Yes Ta >0 |
.It \&.Ft Ta \&No Ta Yes Ta n |
.It \&.Ft Ta \&No Ta Yes Ta n |
.It \&.Ic Ta Yes Ta Yes Ta >0 |
.It \&.Ic Ta Yes Ta Yes Ta >0 |
.It \&.In Ta \&No Ta \&No Ta n |
.It \&.In Ta \&No Ta \&No Ta n |
.It \&.Li Ta Yes Ta Yes Ta >0 |
.It \&.Li Ta Yes Ta Yes Ta n |
.It \&.Nd Ta \&No Ta \&No Ta n |
.It \&.Nd Ta \&No Ta \&No Ta n |
.It \&.Nm Ta Yes Ta Yes Ta n |
.It \&.Nm Ta Yes Ta Yes Ta n |
.It \&.Ot Ta \&No Ta \&No Ta n |
.It \&.Ot Ta \&No Ta \&No Ta n |
.It \&.Pa Ta Yes Ta Yes Ta n |
.It \&.Pa Ta Yes Ta Yes Ta n |
.It \&.Rv Ta \&No Ta \&No Ta 0 |
.It \&.Rv Ta \&No Ta \&No Ta 0 |
.It \&.St Ta \&No Ta Yes Ta 1 |
.It \&.St Ta \&No Ta Yes Ta 1 |
.It \&.Va Ta Yes Ta Yes Ta >0 |
.It \&.Va Ta Yes Ta Yes Ta n |
.It \&.Vt Ta Yes Ta Yes Ta >0 |
.It \&.Vt Ta Yes Ta Yes Ta >0 |
.It \&.Xr Ta Yes Ta Yes Ta >0, <3 |
.It \&.Xr Ta Yes Ta Yes Ta >0, <3 |
.It \&.%A Ta \&No Ta \&No Ta >0 |
.It \&.%A Ta \&No Ta \&No Ta >0 |
Line 803 then the macro accepts an arbitrary number of argument |
|
Line 854 then the macro accepts an arbitrary number of argument |
|
.It \&.Bsx Ta Yes Ta Yes Ta n |
.It \&.Bsx Ta Yes Ta Yes Ta n |
.It \&.Bx Ta Yes Ta Yes Ta n |
.It \&.Bx Ta Yes Ta Yes Ta n |
.It \&.Db Ta \&No Ta \&No Ta 1 |
.It \&.Db Ta \&No Ta \&No Ta 1 |
.It \&.Em Ta Yes Ta Yes Ta >0 |
.It \&.Em Ta Yes Ta Yes Ta n |
.It \&.Fx Ta Yes Ta Yes Ta n |
.It \&.Fx Ta Yes Ta Yes Ta n |
.It \&.Ms Ta \&No Ta Yes Ta >0 |
.It \&.Ms Ta \&No Ta Yes Ta >0 |
.It \&.No Ta Yes Ta Yes Ta 0 |
.It \&.No Ta Yes Ta Yes Ta 0 |
Line 965 should be provided for Linux (\(`a la |
|
Line 1016 should be provided for Linux (\(`a la |
|
.Sq \&Ox , |
.Sq \&Ox , |
.Sq \&Nx |
.Sq \&Nx |
etc.). |
etc.). |
|
.\" LIST-ITEM |
|
.It |
|
There's no way to refer to references in |
|
.Sq \&Rs/Re |
|
blocks. |
.El |
.El |