version 1.199, 2011/08/16 23:44:58 |
version 1.210, 2011/09/18 07:57:16 |
Line 30 language is used to format |
|
Line 30 language is used to format |
|
manuals. |
manuals. |
This reference document describes its syntax, structure, and |
This reference document describes its syntax, structure, and |
usage. |
usage. |
The reference implementation is |
The reference implementation for |
|
.Nm |
|
formatting is |
.Xr mandoc 1 ; |
.Xr mandoc 1 ; |
the |
the |
.Sx COMPATIBILITY |
.Sx COMPATIBILITY |
section describes compatibility with other troff \-mdoc implementations. |
section describes compatibility with other implementations. |
.Pp |
.Pp |
An |
An |
.Nm |
.Nm |
Line 42 document follows simple rules: lines beginning with th |
|
Line 44 document follows simple rules: lines beginning with th |
|
character |
character |
.Sq \&. |
.Sq \&. |
are parsed for macros. |
are parsed for macros. |
Text lines, those not beginning with the control character, are |
Lines not beginning with the control character are |
interpreted within the scope of prior macros: |
interpreted within the scope of prior macros: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Sh Macro lines change control state. |
\&.Sh Macro lines change control state. |
Line 52 Text lines are interpreted within the current state. |
|
Line 54 Text lines are interpreted within the current state. |
|
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the space |
documents may contain only graphable 7-bit ASCII characters, the space |
character, and, in certain circumstances, the tab character. |
character, and, in certain circumstances, the tab character. |
.Pp |
The back-space character |
If the first character of a text line is a space, that line is printed |
.Sq \e |
with a leading newline. |
indicates the start of an escape sequence for |
|
.Sx Comments , |
|
.Sx Predefined Strings , |
|
and |
|
.Sx Special Characters . |
.Ss Comments |
.Ss Comments |
Text following a |
Text following an escaped double-quote |
.Sq \e\*q , |
.Sq \e\(dq , |
whether in a macro or text line, is ignored to the end of |
whether in a macro or text line, is ignored to the end of |
line. |
line. |
A macro line with only a control character and comment escape, |
A macro line beginning with a control character and comment escape |
.Sq \&.\e\*q , |
.Sq \&.\e\(dq |
is also ignored. |
is also ignored. |
Macro lines with only a control character and optional whitespace are |
Furthermore, |
|
macro lines with only a control character and optional trailing |
|
whitespace are |
stripped from input. |
stripped from input. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
\&.\e\(dq This is a comment line. |
|
\&.\e\(dq The next line is ignored: |
|
\&. |
|
\&.Em Emphasis \e\(dq This is also a comment. |
|
.Ed |
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and text lines. |
Special characters are used to encode special glyphs and are rendered |
|
differently across output media. |
|
They may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
.Sq \e |
.Sq \e |
followed by either an open-parenthesis |
followed by either an open-parenthesis |
Line 76 for two-character sequences; an open-bracket |
|
Line 94 for two-character sequences; an open-bracket |
|
for n-character sequences (terminated at a close-bracket |
for n-character sequences (terminated at a close-bracket |
.Sq \&] ) ; |
.Sq \&] ) ; |
or a single one character sequence. |
or a single one character sequence. |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li \e(em |
|
Two-letter em dash escape. |
|
.It Li \ee |
|
One-letter backslash escape. |
|
.El |
|
.Pp |
See |
See |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
for a complete list. |
for a complete list. |
Examples include |
|
.Sq \e(em |
|
.Pq em-dash |
|
and |
|
.Sq \ee |
|
.Pq back-slash . |
|
.Ss Text Decoration |
.Ss Text Decoration |
Terms may be text-decorated using the |
Terms may be text-decorated using the |
.Sq \ef |
.Sq \ef |
escape followed by an indicator: B (bold), I (italic), R (Roman), or P |
escape followed by an indicator: B (bold), I (italic), R (regular), or P |
(revert to previous mode): |
(revert to previous mode). |
.Pp |
A numerical representation 3, 2, or 1 (bold, italic, and regular, |
.Dl \efBbold\efR \efIitalic\efP |
|
.Pp |
|
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
|
respectively) may be used instead. |
respectively) may be used instead. |
If a macro opens a font scope after calling |
If a macro opens a font scope after calling |
.Sq \ef , |
.Sq \ef , |
Line 105 mode will be restored upon exiting the |
|
Line 123 mode will be restored upon exiting the |
|
.Sx \&Bf |
.Sx \&Bf |
scope. |
scope. |
.Pp |
.Pp |
Note this form is |
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li \efBbold\efR |
|
Write in bold, then switch to regular font mode. |
|
.It Li \efIitalic\efP |
|
Write in italic, then return to previous font mode. |
|
.El |
|
.Pp |
|
Text decoration is |
.Em not |
.Em not |
recommended for |
recommended for |
.Nm , |
.Nm , |
which encourages semantic annotation. |
which encourages semantic annotation. |
.Ss Predefined Strings |
.Ss Predefined Strings |
Historically, |
Predefined strings, like |
troff |
|
also defined a set of package-specific |
|
.Dq predefined strings , |
|
which, like |
|
.Sx Special Characters , |
.Sx Special Characters , |
mark special output characters and strings by way of input codes. |
mark special output glyphs. |
Predefined strings are escaped with the slash-asterisk, |
Predefined strings are escaped with the slash-asterisk, |
.Sq \e* : |
.Sq \e* : |
single-character |
single-character |
|
|
.Sq \e*(XX , |
.Sq \e*(XX , |
and N-character |
and N-character |
.Sq \e*[N] . |
.Sq \e*[N] . |
See |
.Pp |
.Xr mandoc_char 7 |
Examples: |
for a complete list. |
.Bl -tag -width Ds -offset indent -compact |
Examples include |
.It Li \e*(Am |
.Sq \e*(Am |
Two-letter ampersand predefined string. |
.Pq ampersand |
.It Li \e*q |
and |
One-letter double-quote predefined string. |
.Sq \e*(Ba |
.El |
.Pq vertical bar . |
.Pp |
|
These strings are set using |
|
.Xr roff 7 , |
|
although |
|
.Nm |
|
consists of several pre-set escapes listed in |
|
.Xr mandoc_char 7 . |
.Ss Whitespace |
.Ss Whitespace |
Whitespace consists of the space character. |
Whitespace consists of the space character. |
In text lines, whitespace is preserved within a line; unescaped |
In text lines, whitespace is preserved within a line. |
trailing spaces are stripped from input (unless in a literal context). |
In macro lines, whitespace delimits arguments and is discarded. |
Blank text lines, which may include whitespace, are only permitted |
|
within literal contexts. |
|
.Pp |
.Pp |
In general, trailing whitespace on input lines is discouraged |
Unescaped trailing spaces are stripped from text line input unless in a |
for reasons of clarity and portability. |
literal context. |
|
In general, trailing whitespace on any input line is discouraged for |
|
reasons of portability. |
In the rare case that a blank character is needed at the end of an |
In the rare case that a blank character is needed at the end of an |
input line, it may be forced by |
input line, it may be forced by |
.Sq \e\ \e& . |
.Sq \e\ \e& . |
.Pp |
.Pp |
In macro lines, whitespace delimits arguments and is discarded. |
In general, space characters can be rendered as literal |
|
characters by using non-breaking space escapes or |
|
.Sx Quotation . |
|
.Pp |
|
Blank text lines, which may include whitespace, are only permitted |
|
within literal contexts. |
|
If the first character of a text line is a space, that line is printed |
|
with a leading newline. |
.Ss Quotation |
.Ss Quotation |
Macro arguments may be quoted with double-quotes; in this case, |
Macro arguments may be quoted with double-quotes to so that the |
whitespace within the quotes is retained as part of the argument. |
enclosed text is one literal term. |
For example, |
Quoted text, even if whitespace or if it would cause a macro invocation |
|
when unquoted, is considered literal text. |
.Pp |
.Pp |
.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" |
|
.Pp |
|
renders as |
|
.Sq Fn strlen "const char *s" , |
|
while |
|
.Pp |
|
.D1 Pf \. \&Fn strlen "const char *s" |
|
.Pp |
|
would produce |
|
.Sq Fn strlen const char *s . |
|
.Pp |
|
A quoted argument begins with a double-quote preceded by whitespace. |
A quoted argument begins with a double-quote preceded by whitespace. |
The next double-quote not pairwise adjacent to another double-quote |
The next double-quote not pairwise adjacent to another double-quote |
terminates the literal, regardless of surrounding whitespace. |
terminates the literal, regardless of surrounding whitespace. |
.Pp |
.Pp |
In unquoted arguments, space characters can alternatively be included |
Examples: |
by preceding them with a backslash |
.Bl -tag -width Ds -offset indent -compact |
.Pq Sq \e\~ , |
.It Li .Fn strlen \(dqconst char *s\(dq |
but quoting is usually better for clarity. |
Group arguments |
.Pp |
.Qq const char *s |
Note that any quoted text, even if it would cause a macro invocation |
into one function argument. |
when unquoted, is considered literal text. |
If unspecified, |
Thus, the following produces |
.Qq const , |
.Sq Op "Fl a" : |
.Qq char , |
.Bd -literal -offset indent |
and |
\&.Op "Fl a" |
.Qq *s |
.Ed |
would be considered separate arguments. |
.Pp |
.Pq See Sx \&Fn . |
In text lines, quotes are regarded as opaque text. |
.It Li .Op \(dqFl a\(dq |
|
Consider |
|
.Qq \&Fl a |
|
as literal text instead of a flag macro. |
|
.Pq Aee Sx \&Op , \&Fl . |
|
.El |
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments, such as |
Many macros support scaled widths for their arguments. |
stipulating a two-inch list indentation with the following: |
The syntax for a scaled width is |
.Bd -literal -offset indent |
|
\&.Bl -tag -width 2i |
|
.Ed |
|
.Pp |
|
The syntax for scaled widths is |
|
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
where a decimal must be preceded or proceeded by at least one digit. |
where a decimal must be preceded or proceeded by at least one digit. |
Negative numbers, while accepted, are truncated to zero. |
Negative numbers, while accepted, are truncated to zero. |
|
.Pp |
The following scaling units are accepted: |
The following scaling units are accepted: |
.Pp |
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
|
|
is necessarily non-portable across output media. |
is necessarily non-portable across output media. |
See |
See |
.Sx COMPATIBILITY . |
.Sx COMPATIBILITY . |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li \&.Bl -tag -width 2i |
|
two-inch tagged list indentation |
|
.Pq see Sx \&Bl |
|
.It Li \&.sp 2v |
|
two vertical spaces |
|
.Pq see Sx \&sp |
|
.El |
.Ss Sentence Spacing |
.Ss Sentence Spacing |
When composing a manual, make sure that sentences end at the end of |
Sentences should terminate at the end of an input line. |
a line. |
By doing this, a formatter will be able to apply the proper amount of |
By doing so, front-ends will be able to apply the proper amount of |
|
spacing after the end of sentence (unescaped) period, exclamation mark, |
spacing after the end of sentence (unescaped) period, exclamation mark, |
or question mark followed by zero or more non-sentence closing |
or question mark followed by zero or more non-sentence closing |
delimiters |
delimiters |
|
|
.Pp |
.Pp |
The proper spacing is also intelligently preserved if a sentence ends at |
The proper spacing is also intelligently preserved if a sentence ends at |
the boundary of a macro line. |
the boundary of a macro line. |
For example: |
|
.Pp |
.Pp |
.Dl \&.Xr mandoc 1 \&. |
Examples: |
.Dl \&.Fl T \&Ns \&Cm ascii \&. |
.Bd -literal -offset indent -compact |
|
Do not end sentences mid-line like this. Instead, |
|
end a sentence like this. |
|
A macro would end like this: |
|
\&.Xr mandoc 1 \&. |
|
.Ed |
.Sh MANUAL STRUCTURE |
.Sh MANUAL STRUCTURE |
A well-formed |
A well-formed |
.Nm |
.Nm |
Line 292 file for a utility |
|
Line 331 file for a utility |
|
\&.Sh NAME |
\&.Sh NAME |
\&.Nm progname |
\&.Nm progname |
\&.Nd one line about what it does |
\&.Nd one line about what it does |
\&.\e\*q .Sh LIBRARY |
\&.\e\(dq .Sh LIBRARY |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
\&.Sh SYNOPSIS |
\&.Sh SYNOPSIS |
\&.Nm progname |
\&.Nm progname |
\&.Op Fl options |
\&.Op Fl options |
Line 303 file for a utility |
|
Line 342 file for a utility |
|
The |
The |
\&.Nm |
\&.Nm |
utility processes files ... |
utility processes files ... |
\&.\e\*q .Sh IMPLEMENTATION NOTES |
\&.\e\(dq .Sh IMPLEMENTATION NOTES |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
\&.\e\*q .Sh RETURN VALUES |
\&.\e\(dq .Sh RETURN VALUES |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q .Sh ENVIRONMENT |
\&.\e\(dq .Sh ENVIRONMENT |
\&.\e\*q For sections 1, 6, 7, & 8 only. |
\&.\e\(dq For sections 1, 6, 7, & 8 only. |
\&.\e\*q .Sh FILES |
\&.\e\(dq .Sh FILES |
\&.\e\*q .Sh EXIT STATUS |
\&.\e\(dq .Sh EXIT STATUS |
\&.\e\*q For sections 1, 6, & 8 only. |
\&.\e\(dq For sections 1, 6, & 8 only. |
\&.\e\*q .Sh EXAMPLES |
\&.\e\(dq .Sh EXAMPLES |
\&.\e\*q .Sh DIAGNOSTICS |
\&.\e\(dq .Sh DIAGNOSTICS |
\&.\e\*q For sections 1, 4, 6, 7, & 8 only. |
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. |
\&.\e\*q .Sh ERRORS |
\&.\e\(dq .Sh ERRORS |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q .Sh SEE ALSO |
\&.\e\(dq .Sh SEE ALSO |
\&.\e\*q .Xr foobar 1 |
\&.\e\(dq .Xr foobar 1 |
\&.\e\*q .Sh STANDARDS |
\&.\e\(dq .Sh STANDARDS |
\&.\e\*q .Sh HISTORY |
\&.\e\(dq .Sh HISTORY |
\&.\e\*q .Sh AUTHORS |
\&.\e\(dq .Sh AUTHORS |
\&.\e\*q .Sh CAVEATS |
\&.\e\(dq .Sh CAVEATS |
\&.\e\*q .Sh BUGS |
\&.\e\(dq .Sh BUGS |
\&.\e\*q .Sh SECURITY CONSIDERATIONS |
\&.\e\(dq .Sh SECURITY CONSIDERATIONS |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
.Ed |
.Ed |
.Pp |
.Pp |
The sections in an |
The sections in an |
Line 406 macros should follow C header-file conventions. |
|
Line 445 macros should follow C header-file conventions. |
|
.Pp |
.Pp |
And for the third, configurations (section 4): |
And for the third, configurations (section 4): |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Cd \*qit* at isa? port 0x2e\*q |
\&.Cd \(dqit* at isa? port 0x2e\(dq |
\&.Cd \*qit* at isa? port 0x4e\*q |
\&.Cd \(dqit* at isa? port 0x4e\(dq |
.Ed |
.Ed |
.Pp |
.Pp |
Manuals not in these sections generally don't need a |
Manuals not in these sections generally don't need a |
|
|
\(lBbody...\(rB |
\(lBbody...\(rB |
\&.Yc |
\&.Yc |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed |
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed |
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef |
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef |
Line 683 has multiple heads. |
|
Line 721 has multiple heads. |
|
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB |
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB |
\(lBbody...\(rB |
\(lBbody...\(rB |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent |
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
|
|
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ |
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ |
\(lBbody...\(rB \&Yc \(lBtail...\(rB |
\(lBbody...\(rB \&Yc \(lBtail...\(rB |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
Line 753 end of the line. |
|
Line 789 end of the line. |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed |
.It Em Macro Ta Em Callable Ta Em Parsed |
.It Sx \&Aq Ta Yes Ta Yes |
.It Sx \&Aq Ta Yes Ta Yes |
.It Sx \&Bq Ta Yes Ta Yes |
.It Sx \&Bq Ta Yes Ta Yes |
|
|
lists. |
lists. |
It delimits blocks representing table cells; |
It delimits blocks representing table cells; |
these blocks have bodies, but no heads. |
these blocks have bodies, but no heads. |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.El |
.El |
Line 808 then the macro accepts an arbitrary number of argument |
|
Line 842 then the macro accepts an arbitrary number of argument |
|
|
|
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent |
.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments |
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments |
.It Sx \&%A Ta \&No Ta \&No Ta >0 |
.It Sx \&%A Ta \&No Ta \&No Ta >0 |
.It Sx \&%B Ta \&No Ta \&No Ta >0 |
.It Sx \&%B Ta \&No Ta \&No Ta >0 |
Line 970 in the same way as a plain |
|
Line 1003 in the same way as a plain |
|
.Sq \&| |
.Sq \&| |
character. |
character. |
Using this predefined string is not recommended in new manuals. |
Using this predefined string is not recommended in new manuals. |
|
.Sh MACRO OVERVIEW |
|
This overview is sorted such that macros of similar purpose are listed |
|
together, to help find the best macro for any given purpose. |
|
Deprecated macros are not included in the overview, but can be found |
|
in the alphabetical reference below. |
|
.Ss Document preamble and NAME section macros |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Dd Ta document date: Cm $Mdocdate$ | Ar month day , year |
|
.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch |
|
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version |
|
.It Sx \&Nm Ta document name (one argument) |
|
.It Sx \&Nd Ta document description (one line) |
|
.El |
|
.Ss Sections and cross references |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Sh Ta section header (one line) |
|
.It Sx \&Ss Ta subsection header (one line) |
|
.It Sx \&Sx Ta internal cross reference to a section or subsection |
|
.It Sx \&Xr Ta cross reference to another manual page: Ar name section |
|
.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments) |
|
.El |
|
.Ss Displays and lists |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Bd , \&Ed Ta display block: |
|
.Fl Ar type |
|
.Op Fl offset Ar width |
|
.Op Fl compact |
|
.It Sx \&D1 Ta indented display (one line) |
|
.It Sx \&Dl Ta indented literal display (one line) |
|
.It Sx \&Bl , \&El Ta list block: |
|
.Fl Ar type |
|
.Op Fl width Ar val |
|
.Op Fl offset Ar val |
|
.Op Fl compact |
|
.It Sx \&It Ta list item (syntax depends on Fl Ar type ) |
|
.It Sx \&Ta Ta table cell separator in Sx Bl Fl column No lists |
|
.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references) |
|
.El |
|
.Ss Spacing control |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Pf Ta prefix, no following horizontal space (one argument) |
|
.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments) |
|
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) |
|
.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off |
|
.It Sx \&Bk , \&Ek Ta keep block: Fl words |
|
.It Sx \&br Ta force output line break in text mode (no arguments) |
|
.It Sx \&sp Ta force vertical space: Op Ar height |
|
.El |
|
.Ss Semantic markup for command line utilities: |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility |
|
.It Sx \&Fl Ta command line options (flags) (>=0 arguments) |
|
.It Sx \&Cm Ta command modifier (>0 arguments) |
|
.It Sx \&Ar Ta command arguments (>=0 arguments) |
|
.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) |
|
.It Sx \&Ic Ta internal or interactive command (>0 arguments) |
|
.It Sx \&Ev Ta environmental variable (>0 arguments) |
|
.It Sx \&Pa Ta file system path (>=0 arguments) |
|
.El |
|
.Ss Semantic markup for function libraries: |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Lb Ta function library (one argument) |
|
.It Sx \&In Ta include file (one argument) |
|
.It Sx \&Ft Ta function type (>0 arguments) |
|
.It Sx \&Fo , \&Fc Ta function block: Ar funcname |
|
.It Sx \&Fn Ta function name: |
|
.Op Ar functype |
|
.Ar funcname |
|
.Oo |
|
.Op Ar argtype |
|
.Ar argname |
|
.Oc |
|
.It Sx \&Fa Ta function argument (>0 arguments) |
|
.It Sx \&Vt Ta variable type (>0 arguments) |
|
.It Sx \&Va Ta variable name (>0 arguments) |
|
.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments) |
|
.It Sx \&Er Ta error constant (>0 arguments) |
|
.It Sx \&Ev Ta environmental variable (>0 arguments) |
|
.El |
|
.Ss Various semantic markup: |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&An Ta author name (>0 arguments) |
|
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name |
|
.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address |
|
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments) |
|
.It Sx \&Ad Ta memory address (>0 arguments) |
|
.It Sx \&Ms Ta mathematical symbol (>0 arguments) |
|
.It Sx \&Tn Ta tradename (>0 arguments) |
|
.El |
|
.Ss Physical markup |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments) |
|
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments) |
|
.It Sx \&Li Ta typewriter font (literal) (>0 arguments) |
|
.It Sx \&No Ta return to roman font (normal) (no arguments) |
|
.It Sx \&Bf , \&Ef Ta font block: |
|
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy |
|
.El |
|
.Ss Physical enclosures |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text |
|
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text |
|
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text |
|
.It Sx \&Ql Ta single-quoted literal text: Ql text |
|
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text |
|
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text |
|
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text |
|
.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text |
|
.It Sx \&Eo , \&Ec Ta generic enclosure |
|
.El |
|
.Ss Text production |
|
.Bl -column "Brq, Bro, Brc" description |
|
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ... |
|
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ... |
|
.It Sx \&St Ta reference to a standards document (one argument) |
|
.It Sx \&Ux Ta Ux |
|
.It Sx \&At Ta At |
|
.It Sx \&Bx Ta Bx |
|
.It Sx \&Bsx Ta Bsx |
|
.It Sx \&Nx Ta Nx |
|
.It Sx \&Fx Ta Fx |
|
.It Sx \&Ox Ta Ox |
|
.It Sx \&Dx Ta Dx |
|
.El |
.Sh REFERENCE |
.Sh REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all macros, arranged |
alphabetically. |
alphabetically. |
Line 2063 section, this macro starts a new output line, |
|
Line 2220 section, this macro starts a new output line, |
|
and a blank line is automatically inserted between function definitions. |
and a blank line is automatically inserted between function definitions. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname \(dqint arg0\(dq |
.Dl \&.Fn funcname arg0 |
.Dl \&.Fn funcname arg0 |
.Pp |
.Pp |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
Line 2269 line itself; on following lines, only the |
|
Line 2426 line itself; on following lines, only the |
|
.Sx \&Ta |
.Sx \&Ta |
macro can be used to delimit cells, and |
macro can be used to delimit cells, and |
.Sx \&Ta |
.Sx \&Ta |
is only recognized as a macro when called by other macros, |
is only recognised as a macro when called by other macros, |
not as the first macro on a line. |
not as the first macro on a line. |
.Pp |
.Pp |
Note that quoted strings may span tab-delimited cells on an |
Note that quoted strings may span tab-delimited cells on an |
Line 2329 Its syntax is as follows: |
|
Line 2486 Its syntax is as follows: |
|
.D1 Pf \. Sx \&Lk Ar uri Op Ar name |
.D1 Pf \. Sx \&Lk Ar uri Op Ar name |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q |
.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq |
.Dl \&.Lk http://bsd.lv |
.Dl \&.Lk http://bsd.lv |
.Pp |
.Pp |
See also |
See also |
Line 2843 The following standards are recognised: |
|
Line 3000 The following standards are recognised: |
|
.St -ieee754 |
.St -ieee754 |
.It \-iso8802-3 |
.It \-iso8802-3 |
.St -iso8802-3 |
.St -iso8802-3 |
|
.It \-iso8601 |
|
.St -iso8601 |
.It \-ieee1275-94 |
.It \-ieee1275-94 |
.St -ieee1275-94 |
.St -ieee1275-94 |
.It \-xpg3 |
.It \-xpg3 |
Line 3061 Newer groff and mandoc print |
|
Line 3220 Newer groff and mandoc print |
|
and the arguments. |
and the arguments. |
.It |
.It |
.Sx \&Bl Fl column |
.Sx \&Bl Fl column |
does not recognize trailing punctuation characters when they immediately |
does not recognise trailing punctuation characters when they immediately |
precede tabulator characters, but treats them as normal text and |
precede tabulator characters, but treats them as normal text and |
outputs a space before them. |
outputs a space before them. |
.It |
.It |
Line 3173 The following features are unimplemented in mandoc: |
|
Line 3332 The following features are unimplemented in mandoc: |
|
.Fl offset Ar center |
.Fl offset Ar center |
and |
and |
.Fl offset Ar right . |
.Fl offset Ar right . |
Groff does not implement centered and flush-right rendering either, |
Groff does not implement centred and flush-right rendering either, |
but produces large indentations. |
but produces large indentations. |
.It |
.It |
The |
The |
Line 3229 utility written by Kristaps Dzonsons appeared in |
|
Line 3388 utility written by Kristaps Dzonsons appeared in |
|
The |
The |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons , |
|
.Mt kristaps@bsd.lv . |