mandoc/man.7 - diff

Return to man.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.7 between version 1.44 and 1.60

version 1.44, 2009/11/02 09:53:15

version 1.60, 2010/03/27 10:22:28

Line 67 line termination.

Blank lines are acceptable; where found, the output will assert a

vertical space.

.Pp

The

.Sq \ec

escape is common in historical

.Nm

documents; if encountered at the end of a word, it ensures that the

subsequent word isn't off-set by whitespace.

.Ss Comments

Text following a

.Sq \e\*" ,

Line 109 and

Line 101 and

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

escape followed by an indicator: B (bold), I, (italic), or P and R

escape followed by an indicator: B (bold), I, (italic), R (Roman), or P

(Roman, or reset).

(revert to previous mode):

.Pp

.D1 \efBbold\efR \efIitalic\efP

.Pp

A numerical representation 3, 2, or 1 (bold, italic, and Roman,

respectively) may be used instead. A text decoration is only valid, if

specified in free-form text, until the next macro invocation; if

specified within a macro, it's only valid until the macro closes scope.

Note that macros like

.Sx \&BR

open and close a font scope with each argument.

.Pp

Text may also be sized with the

.Sq \es

escape, whose syntax is one of

.Sq \es+-n

for one-digit numerals;

.Sq \es(+-nn

.Sq \es+-(nn

for two-digit numerals; and

.Sq \es[+-N] ,

.Sq \es+-[N] ,

.Sq \es'+-N' ,

.Sq \es+-'N'

for arbitrary-digit numerals:

.Pp

.D1 \es+1bigger\es-1

.D1 \es[+10]much bigger\es[-10]

.D1 \es+(10much bigger\es-(10

.D1 \es+'100'much much bigger\es-'100'

.Pp

Both

.Sq \es

and

.Sq \ef

attributes are forgotten when entering or exiting a macro block.

.Ss Whitespace

Line 266 the C library, this may be as follows:

Line 295 the C library, this may be as follows:

.D1 Standard C Library (libc, -lc)

.It Em SYNOPSIS

Documents the utility invocation syntax, function call syntax, or device

configuration.

.Pp

For the first, utilities (sections 1, 6, and 8), this is

generally structured as follows:

Line 281 And for the third, configurations (section 4):

Line 310 And for the third, configurations (section 4):

.Pp

.D1 \&.B name* at cardbus ? function ?

.Pp

Manuals not in these sections generally don't need a

.Em SYNOPSIS .

.It Em DESCRIPTION

This expands upon the brief, one-line description in

.Em NAME .

It usually contains a break-down of the options (if documenting a

command).

Line 332 Documents error handling in sections 2, 3, and 9.

Line 361 Documents error handling in sections 2, 3, and 9.

.It Em SEE ALSO

References other manuals with related topics. This section should exist

for most manuals.

.Pp

.D1 \&.BR bar \&( 1 \&),

.Pp

Line 374 Documents any security precautions that operators shou

Line 403 Documents any security precautions that operators shou

Macros are one to three three characters in length and begin with a

control character ,

.Sq \&. ,

at the beginning of the line. An arbitrary amount of whitespace may

at the beginning of the line. The

sit between the control character and the macro name. Thus, the

.Sq \(aq

following are equivalent:

macro control character is also accepted. An arbitrary amount of

whitespace (spaces or tabs) may sit between the control character and

the macro name. Thus, the following are equivalent:

.Bd -literal -offset indent

\&.PP

\&.\ \ \ PP

Line 394 subsequent lines until closed by another block macro.

Line 425 subsequent lines until closed by another block macro.

.Ss Line Macros

Line macros are generally scoped to the current line, with the body

consisting of zero or more arguments. If a macro is scoped to the next

line and the line arguments are empty, the next line is used instead,

line and the line arguments are empty, the next line, which must be

else the general syntax is used. Thus:

text, is used instead. Thus:

.Bd -literal -offset indent

\&.I

foo

Line 404 foo

Line 435 foo

.Pp

is equivalent to

.Sq \&.I foo .

If next-line macros are invoked consecutively, only the last is used; in

If next-line macros are invoked consecutively, only the last is used.

other words, if a next-line macro is preceded by a block macro, it is

If a next-line macro is followed by a non-next-line macro, an error is

ignored.

raised (unless in the case of

.Sx \&br ,

.Sx \&sp ,

.Sx \&Sp ,

.Sx \&na ) .

.Pp

The syntax is as follows:

.Bd -literal -offset indent

\&.YO \(lBbody...\(rB

\(lBbody...\(rB

.Ed

.Pp

.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"

.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"

.It Em Macro Ta Em Arguments Ta Em Scope

.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes

.It Sx \&B Ta n Ta next-line

.It Sx \&B Ta n Ta next-line Ta \&

.It Sx \&BI Ta n Ta current

.It Sx \&BI Ta n Ta current Ta \&

.It Sx \&BR Ta n Ta current

.It Sx \&BR Ta n Ta current Ta \&

.It Sx \&DT Ta 0 Ta current

.It Sx \&DT Ta 0 Ta current Ta \&

.It Sx \&I Ta n Ta next-line

.It Sx \&I Ta n Ta next-line Ta \&

.It Sx \&IB Ta n Ta current

.It Sx \&IB Ta n Ta current Ta \&

.It Sx \&IR Ta n Ta current

.It Sx \&IR Ta n Ta current Ta \&

.It Sx \&PD Ta n Ta current

.\" .It Sx \&PD Ta n Ta current Ta compat

.It Sx \&R Ta n Ta next-line

.It Sx \&R Ta n Ta next-line Ta \&

.It Sx \&RB Ta n Ta current

.It Sx \&RB Ta n Ta current Ta \&

.It Sx \&RI Ta n Ta current

.It Sx \&RI Ta n Ta current Ta \&

.It Sx \&SB Ta n Ta next-line

.It Sx \&SB Ta n Ta next-line Ta \&

.It Sx \&SM Ta n Ta next-line

.It Sx \&SM Ta n Ta next-line Ta \&

.It Sx \&TH Ta >1, <6 Ta current

.It Sx \&TH Ta >1, <6 Ta current Ta \&

.It Sx \&UC Ta n Ta current

.\" .It Sx \&UC Ta n Ta current Ta compat

.It Sx \&br Ta 0 Ta current

.It Sx \&br Ta 0 Ta current Ta compat

.It Sx \&fi Ta 0 Ta current

.It Sx \&fi Ta 0 Ta current Ta compat

.It Sx \&i Ta n Ta current

.It Sx \&i Ta n Ta current Ta compat

.It Sx \&na Ta 0 Ta current

.It Sx \&na Ta 0 Ta current Ta compat

.It Sx \&nf Ta 0 Ta current

.It Sx \&nf Ta 0 Ta current Ta compat

.It Sx \&r Ta 0 Ta current

.It Sx \&r Ta 0 Ta current Ta compat

.It Sx \&sp Ta 1 Ta current

.It Sx \&sp Ta 1 Ta current Ta compat

.\" .It Sx \&Sp Ta 0 Ta current Ta compat

.\" .It Sx \&Vb Ta <1 Ta current Ta compat

.\" .It Sx \&Ve Ta 0 Ta current Ta compat

.El

.Pp

The

Macros marked as

.Sx \&PD ,

.Qq compat

.Sx \&RS ,

are included for compatibility with the significant corpus of existing

.Sx \&RE ,

manuals that mix dialects of roff. These macros should not be used for

.Sx \&UC ,

portable

.Sx \&br ,

.Nm

.Sx \&fi ,

manuals.

.Sx \&i ,

.Sx \&na ,

.Sx \&nf ,

.Sx \&r ,

and

.Sx \&sp

macros should not be used. They're included for compatibility.

.Ss Block Macros

Block macros are comprised of a head and body. Like for in-line macros,

the head is scoped to the current line and, in one circumstance, the

next line; the body is scoped to subsequent lines and is closed out by a

next line (the next-line stipulations as in

subsequent block macro invocation.

.Sx Line Macros

apply here as well).

.Pp

The syntax is as follows:

.Bd -literal -offset indent

\&.YO \(lBhead...\(rB

\(lBhead...\(rB

Line 475 sub-section, closed by a section or

Line 512 sub-section, closed by a section or

.Sx \&SS ;

part, closed by a section, sub-section, or

.Sx \&RE ;

or paragraph, closed by a section, sub-section, part,

.Sx \&HP ,

.Sx \&IP ,

.Sx \&LP ,

Line 486 or

Line 523 or

No closure refers to an explicit block closing macro.

.Pp

.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent

As a rule, block macros may not be nested; thus, calling a block macro

.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope

while another block macro scope is open, and the open scope is not

.It Sx \&HP Ta <2 Ta current Ta paragraph

implicitly closed, is syntactically incorrect.

.It Sx \&IP Ta <3 Ta current Ta paragraph

.It Sx \&LP Ta 0 Ta current Ta paragraph

.Pp

.It Sx \&P Ta 0 Ta current Ta paragraph

.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"

.It Sx \&PP Ta 0 Ta current Ta paragraph

.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes

.It Sx \&RE Ta 0 Ta current Ta none

.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&

.It Sx \&RS Ta 1 Ta current Ta part

.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&

.It Sx \&SH Ta >0 Ta next-line Ta section

.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&

.It Sx \&SS Ta >0 Ta next-line Ta sub-section

.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&

.It Sx \&TP Ta n Ta next-line Ta paragraph

.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&

.It Sx \&RE Ta 0 Ta current Ta none Ta compat

.It Sx \&RS Ta 1 Ta current Ta part Ta compat

.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&

.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&

.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&

.El

.Pp

Macros marked

.Qq compat

are as mentioned in

.Sx Line Macros .

.Pp

If a block macro is next-line scoped, it may only be followed by in-line

macros (excluding

macros for decorating text.

.Sx \&DT ,

.Sx \&PD ,

.Sx \&TH ,

.Sx \&UC ,

.Sx \&br ,

.Sx \&na ,

.Sx \&sp ,

.Sx \&nf ,

and

.Sx \&fi ) .

.Sh REFERENCE

Line 534 and

Line 572 and

.Ss \&BI

Text is rendered alternately in bold face and italic. Thus,

.Sq .BI this word and that

causes

.Sq this

and

.Sq and

to render in bold face, while

.Sq word

and

.Sq that

render in italics. Whitespace between arguments is omitted in output.

.Pp

Examples:

.Bd -filled -offset indent

.Pf \. Sx \&BI

bold italic bold italic

.Ed

.Pp

.D1 \&.BI bold italic bold italic

.Pp

The output of this example will be emboldened

.Dq bold

and italicised

Line 604 If specified, it's saved for later paragraph left-marg

Line 640 If specified, it's saved for later paragraph left-marg

saved or default width is used.

.Pp

See also

.Sx IP ,

.Sx \&IP ,

.Sx LP ,

.Sx \&LP ,

.Sx P ,

.Sx \&P ,

.Sx PP ,

.Sx \&PP ,

and

.Sx TP .

.Sx \&TP .

.Ss \&I

Line 661 argument is used as a leading term, flushed to the lef

Line 697 argument is used as a leading term, flushed to the lef

useful for bulleted paragraphs and so on.

.Pp

See also

.Sx HP ,

.Sx \&HP ,

.Sx LP ,

.Sx \&LP ,

.Sx P ,

.Sx \&P ,

.Sx PP ,

.Sx \&PP ,

and

.Sx TP .

.Sx \&TP .

.Ss \&IR

Line 692 subsequent paragraph, sub-section, section, or end of

Line 728 subsequent paragraph, sub-section, section, or end of

paragraph left-margin width is re-set to the default.

.Pp

See also

.Sx HP ,

.Sx \&HP ,

.Sx IP ,

.Sx \&IP ,

.Sx P ,

.Sx \&P ,

.Sx PP ,

.Sx \&PP ,

and

.Sx TP .

.Sx \&TP .

.Ss \&P

Line 705 Synonym for

Line 741 Synonym for

.Sx \&LP .

.Pp

See also

.Sx HP ,

.Sx \&HP ,

.Sx IP ,

.Sx \&IP ,

.Sx LP ,

.Sx \&LP ,

.Sx PP ,

.Sx \&PP ,

and

.Sx TP .

.Sx \&TP .

.Ss \&PP

Line 718 Synonym for

Line 754 Synonym for

.Sx \&LP .

.Pp

See also

.Sx HP ,

.Sx \&HP ,

.Sx IP ,

.Sx \&IP ,

.Sx LP ,

.Sx \&LP ,

.Sx P ,

.Sx \&P ,

and

.Sx TP .

.Sx \&TP .

.Ss \&R

Line 792 The

Line 828 The

.Cm width

argument must conform to

.Sx Scaling Widths .

If not specified, the saved or default width is used.

.Ss \&SB

Line 841 string replaces the default rendered volume, which is

Line 877 string replaces the default rendered volume, which is

manual section.

.Pp

Examples:

.Bd -filled -offset indent

.Pp

\&.TH CVS 5 "1992-02-12" GNU

.D1 \&.TH CVS 5 "1992-02-12" GNU

.Ed

.Ss \&TP

Line 864 If specified, it's saved for later paragraph left-marg

Line 899 If specified, it's saved for later paragraph left-marg

unspecified, the saved or default width is used.

.Pp

See also

.Sx HP ,

.Sx \&HP ,

.Sx IP ,

.Sx \&IP ,

.Sx LP ,

.Sx \&LP ,

.Sx P ,

.Sx \&P ,

and

.Sx PP .

.Sx \&PP .

.\" .

.\" .Ss \&PD

.\" Has no effect. Included for compatibility.

.\" .

.\" .Ss \&UC

.\" Has no effect. Included for compatibility.

.Ss \&PD

Has no effect. Included for compatibility.

.Ss \&UC

Has no effect. Included for compatibility.

.Ss \&br

Breaks the current line. Consecutive invocations have no further effect.

.Pp

Line 893 End literal mode begun by

Line 928 End literal mode begun by

.Ss \&i

Italicise arguments. If no arguments are specified, all subsequent text

Italicise arguments. Synonym for

is italicised.

.Sx \&I .

.Pp

See also

.Sx \&B ,

Line 934 Insert vertical spaces into output with the following

Line 969 Insert vertical spaces into output with the following

.Op Cm height

.Ed

.Pp

Insert

.Cm height

spaces, which must conform to

.Sx Scaling Widths .

Line 945 macro. Defaults to 1, if unspecified.

Line 980 macro. Defaults to 1, if unspecified.

See also

.Sx \&br .

.\" .Ss \&Sp

.\" A synonym for

.\" .Sx \&sp

.\" .Cm 0.5v .

.\" .

.\" .Ss \&Vb

.\" A synonym for

.\" .Sx \&nf .

.\" Accepts an argument (the height of the formatted space) which is

.\" disregarded.

.\" .

.\" .Ss \&Ve

.\" A synonym for

.\" .Sx \&fi .

.\" .

.Sh COMPATIBILITY

This section documents compatibility with other roff implementations, at

This section documents areas of questionable portability between

this time limited to

implementations of the

.Xr groff 1 .

.Nm

.Bl -hyphen

language.

.Pp

.Bl -dash -compact

.It

In quoted literals, groff allowed pair-wise double-quotes to produce a

In quoted literals, GNU troff allowed pair-wise double-quotes to produce

standalone double-quote in formatted output. This idiosyncratic

a standalone double-quote in formatted output. It is not known whether

behaviour is no longer applicable.

this behaviour is exhibited by other formatters.

.It

Blocks of whitespace are stripped from macro and free-form text lines

(except when in literal mode) in mandoc. This is not the case for GNU

troff: for maximum portability, whitespace sensitive blocks should be

enclosed in literal contexts.

.It

The

.Sq sp

.Sx \&sp

macro does not accept negative numbers.

macro does not accept negative values in mandoc. In GNU troff, this

would result in strange behaviour.

.It

Blocks of whitespace are stripped from both macro and free-form text

The

lines (except when in literal mode), while groff would retain whitespace

.Sq \(aq

in free-form text lines.

macro control character, in GNU troff (and prior troffs) suppresses a

newline before macro output; in mandoc, it is an alias for the standard

.Sq \&.

control character.

.El

CVSweb