version 1.57, 2009/08/20 12:08:40 |
version 1.63, 2009/10/19 07:34:43 |
|
|
whether in a macro or free-form text line, is ignored to the end of |
whether in a macro or free-form text line, is ignored to the end of |
line. A macro line with only a control character and comment escape, |
line. A macro line with only a control character and comment escape, |
.Sq \&.\e" , |
.Sq \&.\e" , |
is also ignored. |
is also ignored. Macro lines with only a control charater and optionally |
|
whitespace are stripped from input. |
. |
. |
. |
. |
.Ss Reserved Characters |
.Ss Reserved Characters |
Within a macro line, the following characters are reserved: |
Within a macro line, the following characters are reserved: |
|
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \&. |
.It \&. |
.Pq period |
.Pq period |
Line 207 considered literal text. Thus, the following produces |
|
Line 209 considered literal text. Thus, the following produces |
|
.Pp |
.Pp |
In free-form mode, quotes are regarded as opaque text. |
In free-form mode, quotes are regarded as opaque text. |
. |
. |
|
.Ss Dates |
|
TODO. |
. |
. |
|
.Ss Scaling Widths |
|
Many macros support scaled widths for their arguments, such as |
|
stipulating a two-inch list indentation with the following: |
|
.Bd -literal -offset indent |
|
\&.Bl -tag -width 2i |
|
.Ed |
|
. |
|
.Pp |
|
The syntax for scaled widths is |
|
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
|
where a decimal must be preceded or proceeded by at least one digit. |
|
Negative numbers, while accepted, are truncated to zero. The following |
|
scaling units are accepted: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It c |
|
centimetre |
|
.It i |
|
inch |
|
.It P |
|
pica (~1/6 inch) |
|
.It p |
|
point (~1/72 inch) |
|
.It f |
|
synonym for |
|
.Sq u |
|
.It v |
|
default vertical span |
|
.It m |
|
width of rendered |
|
.Sq m |
|
.Pq em |
|
character |
|
.It n |
|
width of rendered |
|
.Sq n |
|
.Pq en |
|
character |
|
.It u |
|
default horizontal span |
|
.It M |
|
mini-em (~1/100 em) |
|
.El |
|
.Pp |
|
Using anything other than |
|
.Sq m , |
|
.Sq n , |
|
.Sq u , |
|
or |
|
.Sq v |
|
is necessarily non-portable across output media. See |
|
.Sx COMPATIBILITY . |
|
. |
|
. |
.Sh MANUAL STRUCTURE |
.Sh MANUAL STRUCTURE |
Each |
Each |
.Nm |
.Nm |
|
|
\&.Dd $\&Mdocdate$ |
\&.Dd $\&Mdocdate$ |
\&.Dt mdoc 7 |
\&.Dt mdoc 7 |
\&.Os |
\&.Os |
|
\&. |
\&.Sh NAME |
\&.Sh NAME |
\&.Nm mdoc |
\&.Nm foo |
\&.Nd mdoc language reference |
\&.Nd a description goes here |
|
\&.\e\*q The next is for sections 2 & 3 only. |
|
\&.\e\*q .Sh LIBRARY |
|
\&. |
|
\&.Sh SYNOPSIS |
|
\&.Nm foo |
|
\&.Op Fl options |
|
\&.Ar |
|
\&. |
|
\&.Sh DESCRIPTION |
|
The |
|
\&.Nm |
|
utility processes files ... |
|
\&.\e\*q .Sh IMPLEMENTATION NOTES |
|
\&.\e\*q The next is for sections 1 & 8 only. |
|
\&.\e\*q .Sh EXIT STATUS |
|
\&.\e\*q The next is for sections 2, 3, & 9 only. |
|
\&.\e\*q .Sh RETURN VALUES |
|
\&.\e\*q The next is for sections 1, 6, 7, & 8 only. |
|
\&.\e\*q .Sh ENVIRONMENT |
|
\&.\e\*q .Sh FILES |
|
\&.\e\*q .Sh EXAMPLES |
|
\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. |
|
\&.\e\*q .Sh DIAGNOSTICS |
|
\&.\e\*q The next is for sections 2, 3, & 9 only. |
|
\&.\e\*q .Sh ERRORS |
|
\&.\e\*q .Sh SEE ALSO |
|
\&.\e\*q .Xr foobar 1 |
|
\&.\e\*q .Sh STANDARDS |
|
\&.\e\*q .Sh HISTORY |
|
\&.\e\*q .Sh AUTHORS |
|
\&.\e\*q .Sh CAVEATS |
|
\&.\e\*q .Sh BUGS |
|
\&.\e\*q .Sh SECURITY CONSIDERATIONS |
.Ed |
.Ed |
. |
. |
.Pp |
.Pp |
|
|
column indicates that the macro may be called subsequent to the initial |
column indicates that the macro may be called subsequent to the initial |
line-macro. If a macro is not callable, then its invocation after the |
line-macro. If a macro is not callable, then its invocation after the |
initial line macro is interpreted as opaque text, such that |
initial line macro is interpreted as opaque text, such that |
.Sq \&.Fl Sh |
.Sq \&.Fl \&Sh |
produces |
produces |
.Sq Fl Sh . |
.Sq Fl \&Sh . |
. |
. |
.Pp |
.Pp |
The |
The |
|
|
.Pp |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent |
.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It \&Ac Ta Yes Ta Yes Ta opened by \&Ao |
.It \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac |
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
.It \&Bc Ta Yes Ta Yes Ta closed by \&Bo |
.It \&Bc Ta Yes Ta Yes Ta closed by \&Bo |
.It \&Bo Ta Yes Ta Yes Ta opened by \&Bc |
.It \&Bo Ta Yes Ta Yes Ta opened by \&Bc |
.It \&Brc Ta Yes Ta Yes Ta opened by \&Bro |
.It \&Brc Ta Yes Ta Yes Ta opened by \&Bro |
|
|
.It \&Po Ta Yes Ta Yes Ta opened by \&Pc |
.It \&Po Ta Yes Ta Yes Ta opened by \&Pc |
.It \&Qc Ta Yes Ta Yes Ta opened by \&Oo |
.It \&Qc Ta Yes Ta Yes Ta opened by \&Oo |
.It \&Qo Ta Yes Ta Yes Ta closed by \&Oc |
.It \&Qo Ta Yes Ta Yes Ta closed by \&Oc |
.It \&Re Ta \&No Ta \&No Ta opened by \&Rs |
.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs |
.It \&Rs Ta \&No Ta \&No Ta closed by \&Re |
.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re |
.It \&Sc Ta Yes Ta Yes Ta opened by \&So |
.It \&Sc Ta Yes Ta Yes Ta opened by \&So |
.It \&So Ta Yes Ta Yes Ta closed by \&Sc |
.It \&So Ta Yes Ta Yes Ta closed by \&Sc |
.It \&Xc Ta Yes Ta Yes Ta opened by \&Xo |
.It \&Xc Ta Yes Ta Yes Ta opened by \&Xo |
Line 421 then the macro accepts an arbitrary number of argument |
|
Line 513 then the macro accepts an arbitrary number of argument |
|
.Pp |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent |
.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments |
.It \&%A Ta \&No Ta \&No Ta >0 |
.It Sx \&%A Ta \&No Ta \&No Ta >0 |
.It \&%B Ta \&No Ta \&No Ta >0 |
.It Sx \&%B Ta \&No Ta \&No Ta >0 |
.It \&%C Ta \&No Ta \&No Ta >0 |
.It Sx \&%C Ta \&No Ta \&No Ta >0 |
.It \&%D Ta \&No Ta \&No Ta >0 |
.It Sx \&%D Ta \&No Ta \&No Ta >0 |
.It \&%I Ta \&No Ta \&No Ta >0 |
.It Sx \&%I Ta \&No Ta \&No Ta >0 |
.It \&%J Ta \&No Ta \&No Ta >0 |
.It Sx \&%J Ta \&No Ta \&No Ta >0 |
.It \&%N Ta \&No Ta \&No Ta >0 |
.It Sx \&%N Ta \&No Ta \&No Ta >0 |
.It \&%O Ta \&No Ta \&No Ta >0 |
.It Sx \&%O Ta \&No Ta \&No Ta >0 |
.It \&%P Ta \&No Ta \&No Ta >0 |
.It Sx \&%P Ta \&No Ta \&No Ta >0 |
.It \&%R Ta \&No Ta \&No Ta >0 |
.It Sx \&%R Ta \&No Ta \&No Ta >0 |
.It \&%T Ta \&No Ta \&No Ta >0 |
.It Sx \&%T Ta \&No Ta \&No Ta >0 |
.It \&%V Ta \&No Ta \&No Ta >0 |
.It Sx \&%V Ta \&No Ta \&No Ta >0 |
.It \&Ad Ta Yes Ta Yes Ta n |
.It \&Ad Ta Yes Ta Yes Ta n |
.It \&An Ta Yes Ta Yes Ta n |
.It \&An Ta Yes Ta Yes Ta n |
.It \&Ap Ta Yes Ta Yes Ta 0 |
.It \&Ap Ta Yes Ta Yes Ta 0 |
Line 453 then the macro accepts an arbitrary number of argument |
|
Line 545 then the macro accepts an arbitrary number of argument |
|
.It \&Er Ta Yes Ta Yes Ta >0 |
.It \&Er Ta Yes Ta Yes Ta >0 |
.It \&Es Ta \&No Ta \&No Ta 0 |
.It \&Es Ta \&No Ta \&No Ta 0 |
.It \&Ev Ta Yes Ta Yes Ta n |
.It \&Ev Ta Yes Ta Yes Ta n |
.It \&Ex Ta \&No Ta \&No Ta 0 |
.It \&Ex Ta \&No Ta \&No Ta n |
.It \&Fa Ta Yes Ta Yes Ta n |
.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 |
Line 480 then the macro accepts an arbitrary number of argument |
|
Line 572 then the macro accepts an arbitrary number of argument |
|
.It \&Pa Ta Yes Ta Yes Ta n |
.It \&Pa Ta Yes Ta Yes Ta n |
.It \&Pf Ta \&No Ta Yes Ta 1 |
.It \&Pf Ta \&No Ta Yes Ta 1 |
.It \&Pp Ta \&No Ta \&No Ta 0 |
.It \&Pp Ta \&No Ta \&No Ta 0 |
.It \&Rv Ta \&No Ta \&No Ta 0 |
.It \&Rv Ta \&No Ta \&No Ta n |
.It \&Sm Ta \&No Ta \&No Ta 1 |
.It \&Sm Ta \&No Ta \&No Ta 1 |
.It \&St Ta \&No Ta Yes Ta 1 |
.It \&St Ta \&No Ta Yes Ta 1 |
.It \&Sx Ta Yes Ta Yes Ta >0 |
.It \&Sx Ta Yes Ta Yes Ta >0 |
Line 496 then the macro accepts an arbitrary number of argument |
|
Line 588 then the macro accepts an arbitrary number of argument |
|
.El |
.El |
. |
. |
. |
. |
|
.Sh REFERENCE |
|
This section is a canonical reference of all macros, arranged |
|
alphabetically. For the scoping of individual macros, see |
|
.Sx MACRO SYNTAX . |
|
. |
|
.Ss \&%A |
|
Author name of an |
|
.Sx \&Rs |
|
block. Multiple authors should each be accorded their own |
|
.Sq \%%A |
|
line. |
|
.Pp |
|
Author names should be ordered with full or abbreviated forename(s) |
|
first, then full surname. |
|
.Ss \&%B |
|
Book title of an |
|
.Sx \&Rs |
|
block. This macro may also be used in a non-bibliographic context when |
|
referring to book titles. |
|
.Ss \&%C |
|
Publication city or location of an |
|
.Sx \&Rs |
|
block. |
|
.Pp |
|
.Em Compatibility remark : |
|
this macro is not implemented in |
|
.Xr groff 1 . |
|
.Ss \&%D |
|
Publication date of an |
|
.Sx \&Rs |
|
block. This should follow the canonical syntax for |
|
.Sx Dates . |
|
.Ss \&%I |
|
Publisher or issuer name of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%J |
|
Journal name of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%N |
|
Issue number (usually for journals) of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%O |
|
Optional information of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%P |
|
Book or journal page number of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%Q |
|
Institutional author (school, government, etc.) of an |
|
.Sx \&Rs |
|
block. Multiple institutional authors should each be accorded their own |
|
.Sq \&%Q |
|
line. |
|
.Ss \&%R |
|
Technical report name of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&%T |
|
Article title of an |
|
.Sx \&Rs |
|
block. This macro may also be used in a non-bibliographical context |
|
when referring to article titles. |
|
.Ss \&%V |
|
Volume number of an |
|
.Sx \&Rs |
|
block. |
|
.Ss \&Ac |
|
Closes an |
|
.Sx \&Ao |
|
block. Does not have any tail arguments. |
|
.Ss \&Ad |
|
Address construct: usually in the context of an computational address in |
|
memory, not a physical (post) address. |
|
.Pp |
|
Example: |
|
.Bd -literal -offset indent |
|
\&.Ad [0,$] |
|
\&.Ad 0x00000000 |
|
.Ed |
|
.Ss \&An |
|
.Ss \&Ao |
|
Begins a block enclosed by angled brackets. Does not have any head |
|
arguments. |
|
.Pp |
|
Example: |
|
.Bd -literal -offset indent |
|
\&.Fl -key= Ns Ao Ar val Ac |
|
.Ed |
|
.Pp |
|
Note that, although this is overwhelmingly used to note URIs, the |
|
.Sx \&Lk |
|
and |
|
.Sx \&Mt |
|
macros are better suited for this purpose. |
|
.Ss \&Ap |
|
.Ss \&Aq |
|
.Ss \&Ar |
|
.Ss \&At |
|
.Ss \&Bc |
|
.Ss \&Bd |
|
.Ss \&Bf |
|
.Ss \&Bk |
|
.Ss \&Bl |
|
.Ss \&Bo |
|
.Ss \&Bq |
|
.Ss \&Brc |
|
.Ss \&Bro |
|
.Ss \&Brq |
|
.Ss \&Bsx |
|
.Ss \&Bt |
|
.Ss \&Bx |
|
.Ss \&Cd |
|
.Ss \&Cm |
|
.Ss \&D1 |
|
.Ss \&Db |
|
.Ss \&Dc |
|
.Ss \&Dd |
|
.Ss \&Dl |
|
.Ss \&Do |
|
.Ss \&Dq |
|
.Ss \&Dt |
|
.Ss \&Dv |
|
.Ss \&Dx |
|
.Ss \&Ec |
|
.Ss \&Ed |
|
.Ss \&Ef |
|
.Ss \&Ek |
|
.Ss \&El |
|
.Ss \&Em |
|
.Ss \&En |
|
.Ss \&Eo |
|
.Ss \&Er |
|
.Ss \&Es |
|
.Ss \&Ev |
|
.Ss \&Ex |
|
.Ss \&Fa |
|
.Ss \&Fc |
|
.Ss \&Fd |
|
.Ss \&Fl |
|
.Ss \&Fn |
|
.Ss \&Fo |
|
.Ss \&Fr |
|
.Ss \&Ft |
|
.Ss \&Fx |
|
.Ss \&Hf |
|
.Ss \&Ic |
|
.Ss \&In |
|
.Ss \&It |
|
.Ss \&Lb |
|
.Ss \&Li |
|
.Ss \&Lk |
|
.Ss \&Lp |
|
.Ss \&Ms |
|
.Ss \&Mt |
|
.Ss \&Nd |
|
.Ss \&Nm |
|
.Ss \&No |
|
.Ss \&Ns |
|
.Ss \&Nx |
|
.Ss \&Oc |
|
.Ss \&Oo |
|
.Ss \&Op |
|
.Ss \&Os |
|
.Ss \&Ot |
|
.Ss \&Ox |
|
.Ss \&Pa |
|
.Ss \&Pc |
|
.Ss \&Pf |
|
.Ss \&Po |
|
.Ss \&Pp |
|
.Ss \&Pq |
|
.Ss \&Qc |
|
.Ss \&Ql |
|
.Ss \&Qo |
|
.Ss \&Qq |
|
.Ss \&Re |
|
Closes a |
|
.Sx \&Rs |
|
block. Does not have any tail arguments. |
|
.Ss \&Rs |
|
Begins a bibliographic |
|
.Pq Dq reference |
|
block. Does not have any head arguments. The block macro and may only |
|
contain |
|
.Sx \&%A , |
|
.Sx \&%B , |
|
.Sx \&%C , |
|
.Sx \&%D , |
|
.Sx \&%I , |
|
.Sx \&%J , |
|
.Sx \&%N , |
|
.Sx \&%O , |
|
.Sx \&%P , |
|
.Sx \&%Q , |
|
.Sx \&%R , |
|
.Sx \&%T , |
|
and |
|
.Sx \&%V |
|
child macros (at least one must be specified). |
|
.Pp |
|
Example: |
|
.Bd -literal -offset indent |
|
\&.Rs |
|
\&.%A J. E. Hopcroft |
|
\&.%A J. D. Ullman |
|
\&.%B Introduction to Automata Theory, Languages, and Computation |
|
\&.%I Addison-Wesley |
|
\&.%C Reading, Massachusettes |
|
\&.%D 1979 |
|
\&.Re |
|
.Ed |
|
.Pp |
|
If an |
|
.Sx \&Rs |
|
block is used within a SEE ALSO section, a vertical space is asserted |
|
before the rendered output, else the block continues on the current |
|
line. |
|
.Ss \&Rv |
|
.Ss \&Sc |
|
.Ss \&Sh |
|
.Ss \&Sm |
|
.Ss \&So |
|
.Ss \&Sq |
|
.Ss \&Ss |
|
.Ss \&St |
|
.Ss \&Sx |
|
.Ss \&Sy |
|
.Ss \&Tn |
|
.Ss \&Ud |
|
.Ss \&Ux |
|
.Ss \&Va |
|
.Ss \&Vt |
|
.Ss \&Xc |
|
.Ss \&Xo |
|
.Ss \&Xr |
|
.Ss \&br |
|
.Ss \&sp |
|
. |
|
. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility with other roff implementations, at |
This section documents compatibility with other roff implementations, at |
this time limited to |
this time limited to |
|
|
. |
. |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
|
.It |
|
Negative scaling units are now truncated to zero instead of creating |
|
interesting conditions, such as with |
|
.Sq \&sp -1i . |
|
Furthermore, the |
|
.Sq f |
|
scaling unit, while accepted, is rendered as the default unit. |
.It |
.It |
The |
The |
.Sq \-split |
.Sq \-split |