mandoc/man.7 - diff

Return to man.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.7 between version 1.46 and 1.63

version 1.46, 2009/11/02 17:07:30

version 1.63, 2010/05/07 15:49:36

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 17

.Dd $Mdocdate$

.Dt MAN 7

.Os

.Sh NAME

.Nm man

.Nd man language reference

.Sh DESCRIPTION

The

.Nm man

Line 31 language was historically used to format

Line 27 language was historically used to format

.Ux

manuals. This reference document describes its syntax, structure, and

usage.

.Pp

.Bf -emphasis

Do not use

Line 41 to write your manuals.

Line 36 to write your manuals.

Use the

.Xr mdoc 7

language, instead.

.Pp

.Nm

Line 54 prior macros:

Line 48 prior macros:

\&.SH Macro lines change control state.

Other lines are interpreted within the current state.

.Ed

.Sh INPUT ENCODING

.Nm

documents may contain only graphable 7-bit ASCII characters, the

space character, and the tabs character. All manuals must have

.Ux

line termination.

.Pp

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 84 line. A macro line with only a control character and

Line 65 line. A macro line with only a control character and

.Sq \&.\e" ,

is also ignored. Macro lines with only a control character and

optionally whitespace are stripped from input.

.Ss Special Characters

Special characters may occur in both macro and free-form lines.

Sequences begin with the escape character

Line 104 for a complete list. Examples include

Line 83 for a complete list. Examples include

and

.Sq \ee

.Pq back-slash .

.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

Unless specifically escaped, consecutive blocks of whitespace are pruned

from input. These are later re-added, if applicable, by a front-end

utility such as

.Xr mandoc 1 .

.Ss Dates

The

.Sx \&TH

Line 128 macro is the only

Line 138 macro is the only

macro that requires a date. The form for this date is the ISO-8601

standard

.Cm YYYY-MM-DD .

.Ss Scaling Widths

Many macros support scaled widths for their arguments, such as

stipulating a two-inch paragraph indentation with the following:

.Bd -literal -offset indent

\&.HP 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

Line 182 Using anything other than

Line 188 Using anything other than

.Sq v

is necessarily non-portable across output media.

.Pp

If a scaling unit is not provided, the numerical value is interpreted

under the default rules of

Line 195 this differs from

Line 200 this differs from

.Xr mdoc 7 ,

which, if a unit is not provided, will instead interpret the string as

literal text.

.Sh MANUAL STRUCTURE

Each

.Nm

Line 205 document must contain contains at least the

Line 208 document must contain contains at least the

macro describing the document's section and title. It may occur

anywhere in the document, although conventionally, it appears as the

first macro.

.Pp

Beyond

.Sx \&TH ,

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

Line 268 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 283 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 300 which is used for functions. Historically, this infor

Line 302 which is used for functions. Historically, this infor

described in

.Em DIAGNOSTICS ,

a practise that is now discouraged.

.It Em RETURN VALUES

This section is the dual of

.Em EXIT STATUS ,

which is used for commands. It documents the return values of functions

in sections 2, 3, and 9.

.It Em ENVIRONMENT

Documents any usages of environment variables, e.g.,

.Xr environ 7 .

.It Em FILES

Documents files used. It's helpful to document both the file and a

short description of how the file is used (created, modified, etc.).

.It Em EXAMPLES

Example usages. This often contains snippets of well-formed,

well-tested invocations. Make doubly sure that your examples work

properly!

.It Em DIAGNOSTICS

Documents error conditions. This is most useful in section 4 manuals.

Historically, this section was used in place of

.Em EXIT STATUS

for manuals in sections 1, 6, and 8; however, this practise is

discouraged.

.It Em ERRORS

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

Cross-references should conventionally be ordered

first by section, then alphabetically.

.It Em STANDARDS

References any standards implemented or used, such as

.Pp

Line 347 References any standards implemented or used, such as

Line 341 References any standards implemented or used, such as

If not adhering to any standards, the

.Em HISTORY

section should be used.

.It Em HISTORY

The history of any manual without a

.Em STANDARDS

section should be described in this section.

.It Em AUTHORS

Credits to authors, if applicable, should appear in this section.

Authors should generally be noted by both name and an e-mail address.

.It Em CAVEATS

Explanations of common misuses and misunderstandings should be explained

in this section.

.It Em BUGS

Extant bugs should be described in this section.

.It Em SECURITY CONSIDERATIONS

Documents any security precautions that operators should consider.

.El

.Sh MACRO SYNTAX

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

.Ed

.Pp

The

.Nm

Line 389 macros are classified by scope: line scope or block sc

Line 376 macros are classified by scope: line scope or block sc

macros are only scoped to the current line (and, in some situations,

the subsequent line). Block macros are scoped to the current line and

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

.Ed

.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 \&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

\(lBbody...\(rB

.Ed

.Pp

The closure of body scope may be to the section, where a macro is closed

Line 475 sub-section, closed by a section or

Line 459 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 484 or paragraph, closed by a section, sub-section, part,

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

.Sx \&TP .

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

.Pp

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

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

.It Sx \&P 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 \&PP Ta 0 Ta current Ta paragraph

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

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

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

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

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

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

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

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

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

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

.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

This section is a canonical reference to all macros, arranged

alphabetically. For the scoping of individual macros, see

.Sx MACRO SYNTAX .

.Ss \&B

Text is rendered in bold face.

.Pp

Line 531 See also

Line 508 See also

.Sx \&i ,

and

.Sx \&r .

.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

Line 563 See also

Line 538 See also

.Sx \&RI ,

and

.Sx \&IR .

.Ss \&BR

Text is rendered alternately in bold face and roman (the default font).

Whitespace between arguments is omitted in output.

Line 580 See also

Line 553 See also

.Sx \&RI ,

and

.Sx \&IR .

.Ss \&DT

Has no effect. Included for compatibility.

.Ss \&HP

Begin a paragraph whose initial output line is left-justified, but

subsequent output lines are indented, with the following syntax:

Line 608 See also

Line 577 See also

.Sx \&PP ,

and

.Sx \&TP .

.Ss \&I

Text is rendered in italics.

.Pp

Line 620 See also

Line 587 See also

.Sx \&i ,

and

.Sx \&r .

.Ss \&IB

Text is rendered alternately in italics and bold face. Whitespace

between arguments is omitted in output.

Line 637 See also

Line 602 See also

.Sx \&RI ,

and

.Sx \&IR .

.Ss \&IP

Begin an indented paragraph with the following syntax:

.Bd -filled -offset indent

Line 665 See also

Line 628 See also

.Sx \&PP ,

and

.Sx \&TP .

.Ss \&IR

Text is rendered alternately in italics and roman (the default font).

Whitespace between arguments is omitted in output.

Line 682 See also

Line 643 See also

.Sx \&RB ,

and

.Sx \&RI .

.Ss \&LP

Begin an undecorated paragraph. The scope of a paragraph is closed by a

subsequent paragraph, sub-section, section, or end of file. The saved

Line 696 See also

Line 655 See also

.Sx \&PP ,

and

.Sx \&TP .

.Ss \&P

Synonym for

.Sx \&LP .

Line 709 See also

Line 666 See also

.Sx \&PP ,

and

.Sx \&TP .

.Ss \&PP

Synonym for

.Sx \&LP .

Line 722 See also

Line 677 See also

.Sx \&P ,

and

.Sx \&TP .

.Ss \&R

Text is rendered in roman (the default font).

.Pp

Line 734 See also

Line 687 See also

.Sx \&i ,

and

.Sx \&r .

.Ss \&RB

Text is rendered alternately in roman (the default font) and bold face.

Whitespace between arguments is omitted in output.

Line 751 See also

Line 702 See also

.Sx \&RI ,

and

.Sx \&IR .

.Ss \&RE

Explicitly close out the scope of a prior

.Sx \&RS .

.Ss \&RI

Text is rendered alternately in roman (the default font) and italics.

Whitespace between arguments is omitted in output.

Line 773 See also

Line 720 See also

.Sx \&RB ,

and

.Sx \&IR .

.Ss \&RS

Begin a part setting the left margin. The left margin controls the

offset, following an initial indentation, to un-indented text such as

Line 790 The

Line 735 The

.Cm width

argument must conform to

.Sx Scaling Widths .

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

.Ss \&SB

Text is rendered in small size (one point smaller than the default font)

bold face.

.Ss \&SH

Begin a section. The scope of a section is only closed by another

section or the end of file. The paragraph left-margin width is re-set

to the default.

.Ss \&SM

Text is rendered in small size (one point smaller than the default

font).

.Ss \&SS

Begin a sub-section. The scope of a sub-section is closed by a

subsequent sub-section, section, or end of file. The paragraph

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

.Ss \&TH

Sets the title of the manual page with the following syntax:

.Bd -filled -offset indent

Line 841 manual section.

Line 776 manual section.

Examples:

.Pp

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

.Ss \&TP

Begin a paragraph where the head, if exceeding the indentation width, is

followed by a newline; if not, the body follows on the same line after a

Line 867 See also

Line 800 See also

.Sx \&P ,

and

.Sx \&PP .

.\" .

.Ss \&PD

.\" .Ss \&PD

Has no effect. Included for compatibility.

.\" Has no effect. Included for compatibility.

.\" .

.Ss \&UC

.\" .Ss \&UC

Has no effect. Included for compatibility.

.\" Has no effect. Included for compatibility.

.Ss \&br

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

.Pp