version 1.30, 2009/06/17 14:08:47 |
version 1.37, 2009/07/05 19:25:10 |
|
|
language is used to format |
language is used to format |
.Bx |
.Bx |
.Ux |
.Ux |
manuals. In this reference document, we describe the syntax, ontology |
manuals. In this reference document, we describe the syntax and |
and structure of the |
structure of the |
.Nm |
.Nm |
language. Our reference implementation is |
language. Our reference implementation is |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
Line 136 or a single one-character sequence. |
|
Line 136 or a single one-character sequence. |
|
.Pp |
.Pp |
Characters may alternatively be escaped by a slash-asterisk, |
Characters may alternatively be escaped by a slash-asterisk, |
.Sq \e* , |
.Sq \e* , |
with the same combinations as described above. This form is deprecated. |
with the same combinations as described above. |
|
.Pp |
|
Terms may also be text-decorated using the |
|
.Sq \ef |
|
escape followed by a text-decoration letter: B (bold), I, (italic), or P |
|
and R (Roman, or reset). This form is not recommended. |
|
.\" SUB-SECTION |
|
.Ss Whitespace |
|
Unless in literal mode or specifically escaped, consecutive blocks of |
|
whitespace are pruned from input. These are later re-added, if |
|
applicable, by a front-end utility such as |
|
.Xr mandoc 1 . |
.\" SECTION |
.\" SECTION |
.Sh STRUCTURE |
.Sh STRUCTURE |
Macros are classified in an ontology described by their scope rules. |
Each |
Some macros are allowed to deviate from their classifications to |
.Nm |
preserve backward-compatibility with old macro combinations still found |
document must begin with the document prologue, containing, in order, |
in the manual corpus. These are specifically noted on a per-macro |
.Sq \&.Dd , |
basis. |
.Sq \&.Dt , |
|
and |
|
.Sq \&.Os . |
|
Following these, the document body must begin with the NAME section |
|
containing at least one |
|
.Sq \&.Nm |
|
followed by a |
|
.Sq \&.Nd |
|
macro. |
|
.Pp |
|
At least one free-form or macro line must follow this prologue. |
|
.\" |
|
.Ss Classification |
|
Macros are classified 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 278 In-lines have \(>=0 scoped arguments. |
|
Line 305 In-lines have \(>=0 scoped arguments. |
|
|
|
\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
.Ed |
.Ed |
.\" |
.\" SECTION |
.Sh MACROS |
.Sh MACROS |
This section contains a complete list of all |
This section contains a complete list of all |
.Nm |
.Nm |
macros, arranged ontologically. A |
macros, arranged by classification. A |
.Qq callable |
.Qq callable |
macro is invoked subsequent to the initial macro-line macro. A |
macro is invoked subsequent to the initial macro-line macro. A |
.Qq parsable |
.Qq parsable |
|
|
.Bl -dash -compact |
.Bl -dash -compact |
.\" LIST-ITEM |
.\" LIST-ITEM |
.It |
.It |
|
Some character sequences in groff are not handled depending on escape |
|
style, e.g., |
|
.Sq \e(ba |
|
and |
|
.Sq \e*(Ba |
|
may not be interchanged. This is no longer the case: all character |
|
sequences resolve to the same symbol, regardless the escape style. |
|
.\" LIST-ITEM |
|
.It |
|
Blocks of whitespace are stripped from both macro and free-form text |
|
lines (except when in literal mode), while groff would retain whitespace |
|
in free-form text lines. |
|
.\" LIST-ITEM |
|
.It |
Historic groff has many un-callable macros. Most of these (excluding |
Historic groff has many un-callable macros. Most of these (excluding |
some block-level macros) are now callable, conforming to the |
some block-level macros) are now callable, conforming to the |
non-historic groff version. |
non-historic groff version. |
.\" LIST-ITEM |
.\" LIST-ITEM |
.It |
.It |
The vertical bar |
The vertical bar |
.Sq \(Ba |
.Sq \(ba |
made historic groff |
made historic groff |
.Qq go orbital |
.Qq go orbital |
but is a proper delimiter in this implementation. |
but is a proper delimiter in this implementation. |
Line 535 incorrectly by following it with a reserved character |
|
Line 576 incorrectly by following it with a reserved character |
|
delimiter to render. This is not supported. |
delimiter to render. This is not supported. |
.\" LIST-ITEM |
.\" LIST-ITEM |
.It |
.It |
If an special-character control character |
If an special-character control character is escaped |
.Sq \e |
.Sq \e\e , |
is escaped, it will |
it will obviously not render the subsequent sequence. Even newer |
obviously not render the sequence. Even newer versions of groff seem to |
versions of groff seem to dither on this. |
dither on this. |
|
.El |
.El |
.\" SECTION |
.\" SECTION |
.Sh SEE ALSO |
.Sh SEE ALSO |
|
|
There's no way to refer to references in |
There's no way to refer to references in |
.Sq \&.Rs/.Re |
.Sq \&.Rs/.Re |
blocks. |
blocks. |
|
.\" LIST-ITEM |
|
.It |
|
The \-split and \-nosplit arguments to |
|
.Sq \&.An |
|
are inane. |
.El |
.El |