mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.99 and 1.100

version 1.99, 2010/05/12 08:41:17

version 1.100, 2010/05/12 16:45:18

Line 101 for two-character sequences; an open-bracket

.Sq \&[

for n-character sequences (terminated at a close-bracket

.Sq \&] ) ;

or a single one-character sequence. See

or a single one-character sequence.

See

.Xr mandoc_char 7

for a complete list. Examples include

for a complete list.

Examples include

.Sq \e(em

.Pq em-dash

and

Line 118 escape followed by an indicator: B (bold), I, (italic)

Line 120 escape followed by an indicator: B (bold), I, (italic)

.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 valid within

respectively) may be used instead.

A text decoration is valid within

the current font scope only: if a macro opens a font scope alongside

its own scope, such as

.Sx \&Bf

.Cm \&Sy ,

in-scope invocations of

.Sq \ef

are only valid within the font scope of the macro. If

are only valid within the font scope of the macro.

.Sq \ef

is specified outside of any font scope, such as in unenclosed, free-form

text, it will affect the remainder of the document.

Line 174 and N-character

Line 178 and N-character

.Sq \e*[N] .

See

.Xr mandoc_char 7

for a complete list. Examples include

for a complete list.

Examples include

.Sq \e*(Am

.Pq ampersand

and

Line 187 trailing spaces are stripped from input (unless in a l

Line 192 trailing spaces are stripped from input (unless in a l

Blank free-form lines, which may include whitespace, are only permitted

within literal contexts.

.Pp

In macro lines, whitespace delimits arguments and is discarded. If

In macro lines, whitespace delimits arguments and is discarded.

arguments are quoted, whitespace within the quotes is retained.

If arguments are quoted, whitespace within the quotes is retained.

.Ss Quotation

Macro arguments may be quoted with a double-quote to group

space-delimited terms or to retain blocks of whitespace. A quoted

space-delimited terms or to retain blocks of whitespace.

argument begins with a double-quote preceded by whitespace. The next

A quoted argument begins with a double-quote preceded by whitespace.

double-quote not pair-wise adjacent to another double-quote terminates

The next double-quote not pair-wise adjacent to another double-quote

the literal, regardless of surrounding whitespace.

terminates the literal, regardless of surrounding whitespace.

.Pp

This produces tokens

.Sq a" ,

Line 203 This produces tokens

Line 208 This produces tokens

and

.Sq fg" .

Note that any quoted term, be it argument or macro, is indiscriminately

considered literal text. Thus, the following produces

considered literal text.

Thus, the following produces

.Sq \&Em a :

.Bd -literal -offset indent

\&.Em "Em a"

Line 213 In free-form mode, quotes are regarded as opaque text.

Line 219 In free-form mode, quotes are regarded as opaque text.

.Ss Dates

There are several macros in

.Nm

that require a date argument. The canonical form for dates is the

that require a date argument.

American format:

The canonical form for dates is the American format:

.Pp

.D1 Cm Month Day , Year

.Pp

The

.Cm Day

value is an optionally zero-padded numeral. The

value is an optionally zero-padded numeral.

The

.Cm Month

value is the full month name. The

value is the full month name.

The

.Cm Year

value is the full four-digit year.

.Pp

Line 246 stipulating a two-inch list indentation with the follo

Line 254 stipulating a two-inch list indentation with the follo

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

Negative numbers, while accepted, are truncated to zero.

scaling units are accepted:

The following scaling units are accepted:

.Pp

.Bl -tag -width Ds -offset indent -compact

.It c

Line 285 Using anything other than

Line 293 Using anything other than

.Sq u ,

.Sq v

is necessarily non-portable across output media. See

is necessarily non-portable across output media.

See

.Sx COMPATIBILITY .

.Sh MANUAL STRUCTURE

A well-formed

Line 358 utility processes files ...

Line 367 utility processes files ...

.Pp

The sections in a

.Nm

document are conventionally ordered as they appear above. Sections

document are conventionally ordered as they appear above.

should be composed as follows:

Sections should be composed as follows:

.Bl -ohang -offset Ds

.It Em NAME

The name(s) and a short description of the documented material. The

The name(s) and a short description of the documented material.

syntax for this as follows:

The syntax for this as follows:

.Bd -literal -offset indent

\&.Nm name0

\&.Nm name1

Line 383 and

Line 392 and

.Sx \&Nd .

.It Em LIBRARY

The name of the library containing the documented material, which is

assumed to be a function in a section 2 or 3 manual. The syntax for

assumed to be a function in a section 2 or 3 manual.

this is as follows:

The syntax for this is as follows:

.Bd -literal -offset indent

\&.Lb libarm

.Ed

Line 449 Print verbose information.

Line 458 Print verbose information.

.Pp

Manuals not documenting a command won't include the above fragment.

.It Em IMPLEMENTATION NOTES

Implementation-specific notes should be kept here. This is useful when

Implementation-specific notes should be kept here.

implementing standard functions that may have side effects or notable

This is useful when implementing standard functions that may have side

algorithmic implications.

effects or notable algorithmic implications.

.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

which is used for commands.

in sections 2, 3, and 9.

It documents the return values of functions in sections 2, 3, and 9.

.Pp

See

.Sx \&Rv .

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

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

See

.Sx \&Ev .

.It Em FILES

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

Documents files used.

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

It's helpful to document both the file and a short description of how

the file is used (created, modified, etc.).

.Pp

See

.Sx \&Pa .

.It Em EXIT STATUS

Command exit status for section 1, 6, and 8 manuals. This section is

Command exit status for section 1, 6, and 8 manuals.

the dual of

This section is the dual of

.Em RETURN VALUES ,

which is used for functions. Historically, this information was

which is used for functions.

described in

Historically, this information was described in

.Em DIAGNOSTICS ,

a practise that is now discouraged.

.Pp

See

.Sx \&Ex .

.It Em EXAMPLES

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

Example usages.

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

This often contains snippets of well-formed, well-tested invocations.

properly!

Make doubly sure that your examples work properly!

.It Em DIAGNOSTICS

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

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

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

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

See

.Sx \&Er .

.It Em SEE ALSO

References other manuals with related topics. This section should exist

References other manuals with related topics.

for most manuals. Cross-references should conventionally be ordered

This section should exist for most manuals.

first by section, then alphabetically.

Cross-references should conventionally be ordered first by section, then

alphabetically.

.Pp

See

.Sx \&Xr .

.It Em STANDARDS

References any standards implemented or used. If not adhering to any

References any standards implemented or used.

standards, the

If not adhering to any standards, the

.Em HISTORY

section should be used instead.

.Pp

Line 539 Documents any security precautions that operators shou

Line 551 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.

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

An arbitrary amount of whitespace may sit between the control character

following are equivalent:

and the macro name.

Thus, the following are equivalent:

.Bd -literal -offset indent

\&.Pp

\&.\ \ \ \&Pp

.Ed

.Pp

The syntax of a macro depends on its classification. In this section,

The syntax of a macro depends on its classification.

In this section,

.Sq \-arg

refers to macro arguments, which may be followed by zero or more

.Sq parm

Line 560 closes it out.

Line 574 closes it out.

The

.Em Callable

column indicates that the macro may be called subsequent to the initial

line-macro. If a macro is not callable, then its invocation after the

line-macro.

initial line macro is interpreted as opaque text, such that

If a macro is not callable, then its invocation after the initial line

macro is interpreted as opaque text, such that

.Sq \&.Fl \&Sh

produces

.Sq Fl \&Sh .

Line 569 produces

Line 584 produces

The

.Em Parsable

column indicates whether the macro may be followed by further

(ostensibly callable) macros. If a macro is not parsable, subsequent

(ostensibly callable) macros.

macro invocations on the line will be interpreted as opaque text.

If a macro is not parsable, subsequent macro invocations on the line

will be interpreted as opaque text.

.Pp

The

.Em Scope

column, if applicable, describes closure rules.

.Ss Block full-explicit

Multi-line scope closed by an explicit closing macro. All macros

Multi-line scope closed by an explicit closing macro.

contains bodies; only

All macros contains bodies; only

.Sx \&Bf

contains a head.

.Bd -literal -offset indent

Line 625 has multiple heads.

Line 641 has multiple heads.

.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss

.El

.Ss Block partial-explicit

Like block full-explicit, but also with single-line scope. Each

Like block full-explicit, but also with single-line scope.

has at least a body and, in limited circumstances, a head

Each has at least a body and, in limited circumstances, a head

.Po

.Sx \&Fo ,

.Sx \&Eo

Line 703 in a SYNOPSIS section line, else it is

Line 719 in a SYNOPSIS section line, else it is

.Ss In-line

Closed by

.Sx Reserved Characters ,

end of line, fixed argument lengths, and/or subsequent macros. In-line

end of line, fixed argument lengths, and/or subsequent macros.

macros have only text children. If a number (or inequality) of

In-line macros have only text children.

arguments is

If a number (or inequality) of arguments is

.Pq n ,

then the macro accepts an arbitrary number of arguments.

.Bd -literal -offset indent

Line 795 then the macro accepts an arbitrary number of argument

Line 811 then the macro accepts an arbitrary number of argument

.El

.Sh REFERENCE

This section is a canonical reference of all macros, arranged

alphabetically. For the scoping of individual macros, see

alphabetically.

For the scoping of individual macros, see

.Sx MACRO SYNTAX .

.Ss \&%A

Author name of an

Line 876 Examples:

Line 893 Examples:

.D1 \&.Ad [0,$]

.D1 \&.Ad 0x00000000

.Ss \&An

Author name. This macro may alternatively accepts the following

Author name.

arguments, although these may not be specified along with a parameter:

This macro may alternatively accepts the following arguments, although

these may not be specified along with a parameter:

.Bl -tag -width 12n -offset indent

.It Fl split

Renders a line break before each author listing.

Line 888 The opposite of

Line 906 The opposite of

.Pp

In the AUTHORS section, the default is not to split the first author

listing, but all subsequent author listings, whether or not they're

interspersed by other macros or text, are split. Thus, specifying

interspersed by other macros or text, are split.

Thus, specifying

.Fl split

will cause the first listing also to be split. If not in the AUTHORS

will cause the first listing also to be split.

section, the default is not to split.

If not in the AUTHORS section, the default is not to split.

.Pp

Examples:

.D1 \&.An -nosplit

Line 907 are re-set when entering the AUTHORS section, so if on

Line 926 are re-set when entering the AUTHORS section, so if on

in the general document body, it must be re-specified in the AUTHORS

section.

.Ss \&Ao

Begins a block enclosed by angled brackets. Does not have any head

Begins a block enclosed by angled brackets.

arguments.

Does not have any head arguments.

.Pp

Examples:

.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac

Line 916 Examples:

Line 935 Examples:

See also

.Sx \&Aq .

.Ss \&Ap

Inserts an apostrophe without any surrounding white-space. This is

Inserts an apostrophe without any surrounding white-space.

generally used as a grammatic device when referring to the verb form of

This is generally used as a grammatic device when referring to the verb

a function:

form of a function:

.Bd -literal -offset indent

\&.Fn execve Ap d

.Ed

Line 941 statements, which should use

Line 960 statements, which should use

See also

.Sx \&Ao .

.Ss \&Ar

Command arguments. If an argument is not provided, the string

Command arguments.

If an argument is not provided, the string

.Dq file ...

is used as a default.

.Pp

Line 950 Examples:

Line 970 Examples:

.D1 \&.Ar

.D1 \&.Ar arg1 , arg2 .

.Ss \&At

Formats an AT&T version. Accepts at most one parameter:

Formats an AT&T version.

Accepts at most one parameter:

.Bl -tag -width 12n -offset indent

.It Cm v[1-7] | 32v

A version of

Line 980 Closes a

Line 1001 Closes a

.Sx \&Bo

block. Does not have any tail arguments.

.Ss \&Bd

Begins a display block. A display is collection of macros or text which

Begins a display block.

may be collectively offset or justified in a manner different from that

A display is collection of macros or text which may be collectively

of the enclosing context. By default, the block is preceded by a

offset or justified in a manner different from that

vertical space.

of the enclosing context.

By default, the block is preceded by a vertical space.

.Pp

Each display is associated with a type, which must be one of the

following arguments:

Line 1001 Alias for

Line 1023 Alias for

Centre-justify each line.

.El

.Pp

The type must be provided first. Secondary arguments are as follows:

The type must be provided first.

Secondary arguments are as follows:

.Bl -tag -width 12n -offset indent

.It Fl offset Ar width

Offset by the value of

Line 1022 which justifies to the right margin; and

Line 1045 which justifies to the right margin; and

.Ar center ,

which aligns around an imagined centre axis.

.It

As a precalculated width for a named macro. The most popular is the

As a precalculated width for a named macro.

imaginary macro

The most popular is the imaginary macro

.Ar \&Ds ,

which resolves to

.Ar 6n .

Line 1115 and

Line 1138 and

.\" More...

.\" .

.Ss \&Bo

Begins a block enclosed by square brackets. Does not have any head

Begins a block enclosed by square brackets.

arguments.

Does not have any head arguments.

.Pp

Examples:

.Bd -literal -offset indent

Line 1147 Closes a

Line 1170 Closes a

.Sx \&Bro

block. Does not have any tail arguments.

.Ss \&Bro

Begins a block enclosed by curly braces. Does not have any head

Begins a block enclosed by curly braces.

arguments.

Does not have any head arguments.

.Pp

Examples:

.Bd -literal -offset indent

Line 1204 See also

Line 1227 See also

and

.Sx \&Ux .

.Ss \&Cd

Configuration declaration. This denotes strings accepted by

Configuration declaration.

This denotes strings accepted by

.Xr config 8 .

.Pp

Examples:

Line 1214 Examples:

Line 1238 Examples:

this macro is commonly abused by using quoted literals to retain

white-space and align consecutive

.Sx \&Cd

declarations. This practise is discouraged.

declarations.

This practise is discouraged.

.Ss \&Cm

Command modifiers. Useful when specifying configuration options or

Command modifiers.

keys.

Useful when specifying configuration options or keys.

.Pp

Examples:

.D1 \&.Cm ControlPath

Line 1226 Examples:

Line 1251 Examples:

See also

.Sx \&Fl .

.Ss \&D1

One-line indented display. This is formatted by the default rules and

One-line indented display.

is useful for simple indented statements. It is followed by a newline.

This is formatted by the default rules and is useful for simple indented

statements.

It is followed by a newline.

.Pp

Examples:

.D1 \&.D1 \&Fl abcdefgh

Line 1242 Closes a

Line 1269 Closes a

.Sx \&Do

block. Does not have any tail arguments.

.Ss \&Dd

Document date. This is the mandatory first macro of any

Document date.

This is the mandatory first macro of any

.Nm

manual. Its calling syntax is as follows:

manual.

Its calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dd Cm date

.Pp

Line 1268 See also

Line 1297 See also

and

.Sx \&Os .

.Ss \&Dl

One-line intended display. This is formatted as literal text and is

One-line intended display.

useful for commands and invocations. It is followed by a newline.

This is formatted as literal text and is useful for commands and

invocations.

It is followed by a newline.

.Pp

Examples:

.D1 \&.Dl % mandoc mdoc.7 | less

Line 1299 Examples:

Line 1330 Examples:

See also

.Sx \&Do .

.Ss \&Dt

Document title. This is the mandatory second macro of any

Document title.

This is the mandatory second macro of any

.Nm

file. Its calling syntax is as follows:

file.

Its calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch

.Pp

Its arguments are as follows:

.Bl -tag -width Ds -offset Ds

.It Cm title

The document's title (name). This should be capitalised and is

The document's title (name).

required.

This should be capitalised and is required.

.It Cm section

The manual section. This may be one of

The manual section.

This may be one of

.Ar 1

.Pq utilities ,

.Ar 2

Line 1377 or

Line 1411 or

.Ar CON

.Pq contributed manuals .

.It Cm arch

This specifies a specific relevant architecture. If

This specifies a specific relevant architecture.

.Cm volume

is not provided, it may be used in its place, else it may be used

subsequent that. It, too, is optional. It must be one of

subsequent that.

It, too, is optional.

It must be one of

.Ar alpha ,

.Ar amd64 ,

.Ar amiga ,

Line 1453 and

Line 1490 and

.Ss \&Ek

.Ss \&El

.Ss \&Em

Denotes text that should be emphasised. Note that this is a

Denotes text that should be emphasised.

presentation term and should not be used for stylistically decorating

Note that this is a presentation term and should not be used for

technical terms.

stylistically decorating technical terms.

.Pp

Examples:

.D1 \&.Em Warnings!

Line 1480 Examples:

Line 1517 Examples:

.D1 \&.Ev DISPLAY

.D1 \&.Ev PATH

.Ss \&Ex

Inserts text regarding a utility's exit values. This macro must have

Inserts text regarding a utility's exit values.

first the

This macro must have first the

.Fl std

argument specified, then an optional

.Ar utility .

Line 1494 is provided.

Line 1531 is provided.

.Ss \&Fc

.Ss \&Fd

.Ss \&Fl

Command-line flag. Used when listing arguments to command-line

Command-line flag.

utilities. Prints a fixed-width hyphen

Used when listing arguments to command-line utilities.

Prints a fixed-width hyphen

.Sq \-

directly followed by each argument. If no arguments are provided, a hyphen is

directly followed by each argument.

printed followed by a space. If the argument is a macro, a hyphen is

If no arguments are provided, a hyphen is printed followed by a space.

prefixed to the subsequent macro output.

If the argument is a macro, a hyphen is prefixed to the subsequent macro

output.

.Pp

Examples:

.D1 \&.Fl a b c

Line 1537 and

Line 1576 and

.Ss \&Lb

.Ss \&Li

.Ss \&Lk

Format a hyperlink. The calling syntax is as follows:

Format a hyperlink.

The calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Lk Cm uri Op Cm name

.Pp

Line 1575 and

Line 1615 and

.Ss \&Oo

.Ss \&Op

.Ss \&Os

Document operating system version. This is the mandatory third macro of

Document operating system version.

This is the mandatory third macro of

any

.Nm

file. Its calling syntax is as follows:

Line 1584 file. Its calling syntax is as follows:

Line 1625 file. Its calling syntax is as follows:

.Pp

The optional

.Cm system

parameter specifies the relevant operating system or environment. Left

parameter specifies the relevant operating system or environment.

unspecified, it defaults to the local operating system version. This is

Left unspecified, it defaults to the local operating system version.

the suggested form.

This is the suggested form.

.Pp

Examples:

.D1 \&.Os

Line 1632 and

Line 1673 and

.Ss \&Re

Closes a

.Sx \&Rs

block. Does not have any tail arguments.

block.

Does not have any tail arguments.

.Ss \&Rs

Begins a bibliographic

.Pq Dq reference

block. Does not have any head arguments. The block macro may only

block.

contain

Does not have any head arguments.

The block macro may only contain

.Sx \&%A ,

.Sx \&%B ,

.Sx \&%C ,

Line 1684 line.

Line 1727 line.

.Ss \&Tn

.Ss \&Ud

.Ss \&Ux

Format the UNIX name. Accepts no argument.

Format the UNIX name.

Accepts no argument.

.Pp

Examples:

.D1 \&.Ux

Line 1700 and

Line 1744 and

.Sx \&Ox .

.Ss \&Va

.Ss \&Vt

A variable type. This is also used for indicating global variables in the

A variable type.

SYNOPSIS section, in which case a variable name is also specified. Note that

This is also used for indicating global variables in the SYNOPSIS

it accepts

section, in which case a variable name is also specified.

Note that it accepts

.Sx Block partial-implicit

syntax when invoked as the first macro in the SYNOPSIS section, else it

accepts ordinary

Line 1725 and

Line 1770 and

Close a scope opened by

.Sx \&Xo .

.Ss \&Xo

Open an extension scope. This macro originally existed to extend the

Open an extension scope.

9-argument limit of troff; since this limit has been lifted, the macro

This macro originally existed to extend the 9-argument limit of troff;

has been deprecated.

since this limit has been lifted, the macro has been deprecated.

.Ss \&Xr

Link to another manual

.Pq Qq cross-reference .

Line 1739 The

Line 1784 The

.Cm name

and

.Cm section

are the name and section of the linked manual. If

are the name and section of the linked manual.

.Cm section

is followed by non-punctuation, an

.Sx \&Ns

is inserted into the token stream. This behaviour is for compatibility

is inserted into the token stream.

with

This behaviour is for compatibility with

.Xr groff 1 .

.Pp

Examples:

Line 1776 is no longer accepted.

Line 1822 is no longer accepted.

In groff, the

.Sx \&Pa

macro does not format its arguments when used in the FILES section under

certain list types. mandoc does.

certain list types.

mandoc does.

.It

Historic groff does not print a dash for empty

.Sx \&Fl

arguments. mandoc and newer groff implementations do.

arguments.

mandoc and newer groff implementations do.

.It

groff behaves irregularly when specifying

.Sq \ef

.Sx Text Decoration

within line-macro scopes. mandoc follows a consistent system.

within line-macro scopes.

mandoc follows a consistent system.

.It

In mandoc, negative scaling units are truncated to zero; groff would

move to prior lines. Furthermore, the

move to prior lines.

Furthermore, the

.Sq f

scaling unit, while accepted, is rendered as the default unit.

.It

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

standalone double-quote in formatted output. This idiosyncratic

standalone double-quote in formatted output.

behaviour is not applicable in mandoc.

This idiosyncratic behaviour is not applicable in mandoc.

.It

Display types

.Sx \&Bd

Line 1805 are aliases for

Line 1855 are aliases for

.Fl left

in manodc. Furthermore, the

.Fl file Ar file

argument is ignored. Lastly, since text is not right-justified in

argument is ignored.

mandoc (or even groff),

Lastly, since text is not right-justified in mandoc (or even groff),

.Fl ragged

and

.Fl filled

Line 1815 are aliases, as are

Line 1865 are aliases, as are

and

.Fl unfilled .

.It

Historic groff has many un-callable macros. Most of these (excluding

Historic groff has many un-callable macros.

some block-level macros) are now callable.

Most of these (excluding some block-level macros) are now callable.

.It

The vertical bar

.Sq \(ba

Line 1833 lists will restart the sequence only for the sub-list.

Line 1883 lists will restart the sequence only for the sub-list.

Some manuals use

.Sx \&Li

incorrectly by following it with a reserved character and expecting the

delimiter to render. This is not supported in mandoc.

delimiter to render.

This is not supported in mandoc.

.It

In groff, the

.Sx \&Fo

macro only produces the first parameter. This is not the case in

macro only produces the first parameter.

mandoc.

This is not the case in mandoc.

.It

In groff, the

.Sx \&Cd ,

.Sx \&Er ,

and

.Sx \&Ex

macros were stipulated only to occur in certain manual sections. mandoc

macros were stipulated only to occur in certain manual sections.

does not have these restrictions.

mandoc does not have these restrictions.

.El

.Sh SEE ALSO

.Xr mandoc 1 ,

CVSweb