version 1.110, 2010/05/26 10:39:35 |
version 1.117, 2010/06/04 20:57:26 |
|
|
\&.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 |
Line 1408 This is the mandatory second macro of any |
|
Line 1409 This is the mandatory second macro of any |
|
file. |
file. |
Its calling syntax is as follows: |
Its calling syntax is as follows: |
.Pp |
.Pp |
.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch |
.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch |
.Pp |
.Pp |
Its arguments are as follows: |
Its arguments are as follows: |
.Bl -tag -width Ds -offset Ds |
.Bl -tag -width Ds -offset Ds |
.It Cm title |
.It Cm title |
The document's title (name). |
The document's title (name), defaulting to |
This should be capitalised and is required. |
.Qq UNKNOWN |
|
if unspecified. |
|
It should be capitalised. |
.It Cm section |
.It Cm section |
The manual section. |
The manual section. |
This may be one of |
This may be one of |
Line 1451 This may be one of |
|
Line 1454 This may be one of |
|
or |
or |
.Ar paper |
.Ar paper |
.Pq paper . |
.Pq paper . |
It is also required and should correspond to the manual's filename |
It should correspond to the manual's filename suffix and defaults to |
suffix. |
.Qq 1 |
|
if unspecified. |
.It Cm volume |
.It Cm volume |
This overrides the volume inferred from |
This overrides the volume inferred from |
.Ar section . |
.Ar section . |
|
|
.D1 \&.Dt FOO 1 |
.D1 \&.Dt FOO 1 |
.D1 \&.Dt FOO 4 KM |
.D1 \&.Dt FOO 4 KM |
.D1 \&.Dt FOO 9 i386 |
.D1 \&.Dt FOO 9 i386 |
.D1 \&.Dt FOO 9 KM i386 |
|
.Pp |
.Pp |
See also |
See also |
.Sx \&Dd |
.Sx \&Dd |
|
|
.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 1600 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 \&Ic |
.Ss \&Ic |
.Ss \&In |
.Ss \&In |
.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 1910 Heirloom troff, the other significant troff implementa |
|
Line 2034 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 |
|
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." |