version 1.10, 2009/03/20 15:14:01 |
version 1.15, 2009/03/23 16:02:56 |
|
|
.\" SECTION |
.\" SECTION |
.Sh NAME |
.Sh NAME |
.Nm mdoc |
.Nm mdoc |
.Nd mdoc macro reference |
.Nd mdoc language reference |
.\" SECTION |
.\" SECTION |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
|
|
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 . |
Line 529 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 729 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 782 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 819 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 |
|
|
.El |
.El |
.\" SECTION |
.\" SECTION |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mdoctree 1 , |
.Xr mandoc 1 |
.Xr mdoclint 1 , |
|
.Xr mdocterm 1 , |
|
.Xr mdoc 3 |
|
.\" SECTION |
.\" SECTION |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
Line 981 should be provided for Linux (\(`a la |
|
Line 1013 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 |