version 1.111, 2010/05/30 11:00:53 |
version 1.118, 2010/06/04 21:49:39 |
Line 33 section describes compatibility with other troff \-mdo |
|
Line 33 section describes compatibility with other troff \-mdo |
|
.Pp |
.Pp |
An |
An |
.Nm |
.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 |
Line 122 escape followed by an indicator: B (bold), I, (italic) |
|
Line 122 escape followed by an indicator: B (bold), I, (italic) |
|
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
respectively) may be used instead. |
respectively) may be used instead. |
A text decoration is valid within |
A text decoration is valid within |
the current font scope only: if a macro opens a font scope alongside |
the current font scope only: if a macro opens a font scope alongside |
its own scope, such as |
its own scope, such as |
.Sx \&Bf |
.Sx \&Bf |
.Cm \&Sy , |
.Cm \&Sy , |
|
|
\&.Dd $\&Mdocdate$ |
\&.Dd $\&Mdocdate$ |
\&.Dt mdoc 7 |
\&.Dt mdoc 7 |
\&.Os |
\&.Os |
\&. |
|
\&.Sh NAME |
\&.Sh NAME |
\&.Nm foo |
\&.Nm foo |
\&.Nd a description goes here |
\&.Nd a description goes here |
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q .Sh LIBRARY |
\&.\e\*q .Sh LIBRARY |
\&. |
|
\&.Sh SYNOPSIS |
\&.Sh SYNOPSIS |
\&.Nm foo |
\&.Nm foo |
\&.Op Fl options |
\&.Op Fl options |
\&.Ar |
\&.Ar |
\&. |
|
\&.Sh DESCRIPTION |
\&.Sh DESCRIPTION |
The |
The |
\&.Nm |
\&.Nm |
|
|
These dictate the width of columns either as |
These dictate the width of columns either as |
.Sx Scaling Widths |
.Sx Scaling Widths |
or literal text. |
or literal text. |
List entry bodies must be left empty. |
If the initial macro of a |
Column bodies have the following syntax: |
.Fl column |
.Pp |
list is not an |
.D1 .It col1 <TAB> ... coln |
.Sx \&It , |
.D1 .It col1 Ta ... coln |
an |
.D1 .It col1 <TAB> col2 Ta coln |
.Sx \&It |
.Pp |
context spanning each line is implied until an |
where columns may be separated by tabs, the literal string |
.Sx \&It |
.Qq Ta , |
line macro is encountered, at which point list bodies are interpreted as |
or a mixture of both. |
described in the |
These are equivalent except that quoted sections propogate over tabs, |
.Sx \&It |
for example, |
documentation. |
.Pp |
|
.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ; |
|
.Pp |
|
will preserve the semicolon whitespace except for the last. |
|
.It Fl dash |
.It Fl dash |
A list offset by a dash (hyphen). |
A list offset by a dash (hyphen). |
The head of list entries must be empty. |
The head of list entries must be empty. |
Line 1209 after the head as specified by the |
|
Line 1202 after the head as specified by the |
|
.Fl width |
.Fl width |
argument. |
argument. |
.El |
.El |
|
.Pp |
|
See also |
|
.Sx \&It . |
.Ss \&Bo |
.Ss \&Bo |
Begins a block enclosed by square brackets. |
Begins a block enclosed by square brackets. |
Does not have any head arguments. |
Does not have any head arguments. |
|
|
and |
and |
.Sx \&Dl . |
.Sx \&Dl . |
.Ss \&Db |
.Ss \&Db |
|
Start a debugging context. |
|
This macro is parsed, but generally ignored. |
|
Its calling syntax is as follows: |
|
.Pp |
|
.D1 \. Ns Sx \&Db Cm on | off |
.Ss \&Dc |
.Ss \&Dc |
Closes a |
Closes a |
.Sx \&Do |
.Sx \&Do |
|
|
.Ss \&Ef |
.Ss \&Ef |
.Ss \&Ek |
.Ss \&Ek |
.Ss \&El |
.Ss \&El |
|
Ends a list context started by |
|
.Sx \&Bl . |
|
.Pp |
|
See also |
|
.Sx \&Bl |
|
and |
|
.Sx \&It . |
.Ss \&Em |
.Ss \&Em |
Denotes text that should be emphasised. |
Denotes text that should be emphasised. |
Note that this is a presentation term and should not be used for |
Note that this is a presentation term and should not be used for |
Line 1602 is not provided, the document's name as stipulated in |
|
Line 1610 is not provided, the document's name as stipulated in |
|
.Sx \&Nm |
.Sx \&Nm |
is provided. |
is provided. |
.Ss \&Fa |
.Ss \&Fa |
|
Function argument. |
|
This may be invoked for names with or without the corresponding type. |
|
It is also used to specify the field name of a structure. |
|
Most often, the |
|
.Sx \&Fa |
|
macro is used in the |
|
.Em SYNOPSIS |
|
section when documenting multi-line function prototypes. |
|
If invoked with multiple arguments, the arguments are separated by a |
|
comma. |
|
Furthermore, if the following macro is another |
|
.Sx \&Fa , |
|
the last argument will also have a trailing comma. |
|
.Pp |
|
Examples: |
|
.D1 \&.Fa \(dqconst char *p\(dq |
|
.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq |
|
.D1 \&.Fa foo |
.Ss \&Fc |
.Ss \&Fc |
.Ss \&Fd |
.Ss \&Fd |
|
Historically used to document include files. |
|
This usage has been deprecated in favour of |
|
.Sx \&In . |
|
Do not use this macro. |
|
.Pp |
|
See also |
|
.Sx \&In . |
.Ss \&Fl |
.Ss \&Fl |
Command-line flag. |
Command-line flag. |
Used when listing arguments to command-line utilities. |
Used when listing arguments to command-line utilities. |
|
|
.Ss \&Hf |
.Ss \&Hf |
.Ss \&Ic |
.Ss \&Ic |
.Ss \&In |
.Ss \&In |
|
An |
|
.Qq include |
|
file. |
|
In the |
|
.Em SYNOPSIS |
|
section (only if invoked as the line macro), the first argument is |
|
preceded by |
|
.Qq #include , |
|
the arguments is enclosed in angled braces, and a newline is asserted. |
|
In all other invocations, only angled braces will enclose the argument. |
|
.Pp |
|
Examples |
|
.D1 \&.In sys/types |
.Ss \&It |
.Ss \&It |
|
A list item. The syntax of this macro depends on the list type. |
|
.Pp |
|
Lists |
|
of type |
|
.Fl hang , |
|
.Fl ohang , |
|
.Fl inset , |
|
and |
|
.Fl diag |
|
have the following calling syntax: |
|
.Pp |
|
.D1 \. Ns Sx \&It Cm args |
|
.Pp |
|
Lists of type |
|
.Fl bullet , |
|
.Fl dash , |
|
.Fl enum , |
|
.Fl hyphen |
|
and |
|
.Fl item |
|
have the following calling syntax: |
|
.Pp |
|
.D1 \. Ns Sx \&It |
|
.Pp |
|
with subsequent lines interpreted within the scope of the |
|
.Sx \&It |
|
until either a closing |
|
.Sx \&El |
|
or another |
|
.Sx \&It . |
|
.Pp |
|
The |
|
.Fl tag |
|
list has syntax |
|
.Pp |
|
.D1 \. Ns Sx \&It Op Cm args |
|
.Pp |
|
with subsequent lines interpreted as with |
|
.Fl bullet |
|
and family. |
|
The line arguments correspond to the list's left-hand side; body |
|
arguments correspond to the list's contents. |
|
.Pp |
|
The |
|
.Fl column |
|
list is the most complicated. |
|
Its syntax is |
|
.Pp |
|
.D1 \. Ns Sx \&It Op Cm args |
|
.Pp |
|
where |
|
.Cm args |
|
are phrases, a mix of macros and text corresponding to a line column, |
|
delimited by tabs or the special |
|
.Sq \&Ta |
|
pseudo-macro. |
|
Lines subsequent the |
|
.Sx \&It |
|
are interpreted within the scope of the last phrase. |
|
Calling the pseudo-macro |
|
.Sq \&Ta |
|
will open a new phrase scope (this must occur on a macro line to be |
|
interpreted as a macro). Note that the tab phrase delimiter may only be |
|
used within the |
|
.Sx \&It |
|
line itself. |
|
Subsequent this, only the |
|
.Sq \&Ta |
|
pseudo-macro may be used to delimit phrases. |
|
Furthermore, note that quoted sections propogate over tab-delimited |
|
phrases on an |
|
.Sx \&It , |
|
for example, |
|
.Pp |
|
.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ; |
|
.Pp |
|
will preserve the semicolon whitespace except for the last. |
|
.Pp |
|
See also |
|
.Sx \&Bl . |
.Ss \&Lb |
.Ss \&Lb |
Specify a library. |
Specify a library. |
The calling syntax is as follows: |
The calling syntax is as follows: |
|
|
.Ss \&Lp |
.Ss \&Lp |
.Ss \&Ms |
.Ss \&Ms |
.Ss \&Mt |
.Ss \&Mt |
|
Format a |
|
.Qq mailto: |
|
hyperlink. |
|
The calling syntax is as follows: |
|
.Pp |
|
.D1 \. Ns Sx \&Mt Cm address |
|
.Pp |
|
Examples: |
|
.D1 \&.Mt discuss@manpages.bsd.lv |
.Ss \&Nd |
.Ss \&Nd |
.Ss \&Nm |
.Ss \&Nm |
.Ss \&No |
.Ss \&No |
Line 1912 Heirloom troff, the other significant troff implementa |
|
Line 2047 Heirloom troff, the other significant troff implementa |
|
\-mdoc, is similar to historic groff. |
\-mdoc, is similar to historic groff. |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
|
.It |
|
Historic groff formats the |
|
.Sx \&In |
|
badly: trailing arguments are trashed and |
|
.Em SYNOPSIS |
|
is not specially treated. |
|
.It |
|
groff does not accept the |
|
.Sq \&Ta |
|
pseudo-macro as a line macro. |
|
mandoc does. |
.It |
.It |
The comment syntax |
The comment syntax |
.Sq \e." |
.Sq \e." |