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.116

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

version 1.116, 2010/06/03 15:54:27

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 .

.Ss Sentence Spacing

When composing a manual, make sure that your sentences end at the end of

a line.

By doing so, front-ends will be able to apply the proper amount of

spacing after the end of sentence (unescaped) period, exclamation mark,

or question mark followed by zero or more non-sentence closing

delimiters (

.Ns Sq \&) ,

.Sq \&] ,

.Sq \&' ,

.Sq \&" ) .

.Pp

The proper spacing is also intelligently preserved if a sentence ends at

the boundary of a macro line, e.g.,

.Pp

.D1 \&Xr mandoc 1 \.

.D1 \&Fl T \&Ns \&Cm ascii \.

.Sh MANUAL STRUCTURE

A well-formed

.Nm

Line 317 file:

Line 343 file:

\&.Dd $\&Mdocdate$

\&.Dt mdoc 7

\&.Os

\&.

\&.Sh NAME

\&.Nm foo

\&.Nd a description goes here

\&.\e\*q The next is for sections 2 & 3 only.

\&.\e\*q The next is for sections 2, 3, & 9 only.

\&.\e\*q .Sh LIBRARY

\&.

\&.Sh SYNOPSIS

\&.Nm foo

\&.Op Fl options

\&.Ar

\&.

\&.Sh DESCRIPTION

The

\&.Nm

Line 358 utility processes files ...

Line 381 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 406 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, 3, or 9 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 472 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 490 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 528 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 565 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 588 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 598 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 655 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 698 Note that the

Line 728 Note that the

macro is a

.Sx Block partial-implicit

only when invoked as the first macro

in a SYNOPSIS section line, else it is

in a

.Em SYNOPSIS

section line, else it is

.Sx In-line .

.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 827 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 909 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 922 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 942 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 951 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 976 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 986 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 1017 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 1039 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 1061 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 1060 and

Line 1099 and

.Ss \&Bf

.Ss \&Bk

.Ss \&Bl

.\" Begins a list composed of one or more list entries. A list entry is

Begins a list composed of one or more list entries.

.\" specified by the

A list is associated with a type, which is a required argument.

.\" .Sx \&It

Other arguments are

.\" macro, which consists of a head and optional body. By default, a list

.Fl width ,

.\" is preceded by a blank line. A list must specify one of the following

defined per-type as accepting a literal or

.\" list types:

.Sx Scaling Widths

.\" .Bl -tag -width 12n

value;

.\" .It Fl bullet

.Fl offset ,

.\" A list offset by a bullet. The head of list entries must be empty.

also accepting a literal or

.\" List entry bodies are justified after the bullet.

.Sx Scaling Widths

.\" .It Fl column

value setting the list's global offset; and

.\" A columnated list. The number of columns is specified as arguments to

.Fl compact ,

.\" the

suppressing the default vertical space printed before each list entry.

.\" .Sx \&Bl

A list entry is specified by the

.\" macro (the deprecated form of following the invocation of

.Sx \&It

.\" .Fl column

macro, which consists of a head and optional body (depending on the list

.\" is also accepted). Arguments dictate the width of columns specified in

type).

.\" list entries. List entry bodies must be left empty. Columns specified

A list must specify one of the following list types:

.\" in the list entry head are justified to their position in the sequence

.Bl -tag -width 12n -offset indent

.\" of columns.

.It Fl bullet

.\" .It Fl dash

A list offset by a bullet.

.\" A list offset by a dash (hyphen). The head of list entries must be

The head of list entries must be empty.

.\" empty. List entry bodies are justified past the dash.

List entry bodies are positioned after the bullet.

.\" .It Fl diag

The

.\" Like

.Fl width

.\" .Fl inset

argument varies the width of list bodies' left-margins.

.\" lists, but with additional formatting to the head.

.It Fl column

.\" .It Fl enum

A columnated list.

.\" A list offset by a number indicating list entry position. The head of

The

.\" list entries must be empty. List entry bodies are justified past the

.Fl width

.\" enumeration.

argument has no effect.

.\" .It Fl hang

The number of columns is specified as parameters to the

.\" Like

.Sx \&Bl

.\" .Fl tag ,

macro.

.\" but instead of list bodies justifying to the head on the first line,

These dictate the width of columns either as

.\" they trail the head text.

.Sx Scaling Widths

.\" .It Fl hyphen

or literal text.

.\" Synonym for

If the initial macro of a

.\" .Fl dash .

.Fl column

.\" .It Fl inset

list is not an

.\" Like

.Sx \&It ,

.\" .Fl tag ,

.\" but list entry bodies aren't justified.

.Sx \&It

.\" .It Fl item

context spanning each line is implied until an

.\" An un-justified list. This produces blocks of text.

.Sx \&It

.\" .It Fl ohang

line macro is encountered, at which point list bodies are interpreted as

.\" List bodies are placed on the line following the head.

described in the

.\" .It Fl tag

.Sx \&It

.\" A list offset by list entry heads. List entry bodies are justified

documentation.

.\" after the head.

.It Fl dash

.\" .El

A list offset by a dash (hyphen).

.\" .Pp

The head of list entries must be empty.

.\" More...

List entry bodies are positioned past the dash.

.\" .

The

.Fl width

argument varies the width of list bodies' left-margins.

.It Fl diag

.Fl inset ,

but with additional formatting to the head.

The

.Fl width

argument varies the width of list bodies' left-margins.

.It Fl enum

An enumerated list offset by the enumeration from 1.

The head of list entries must be empty.

List entry bodies are positioned after the enumeration.

The

.Fl width

argument varies the width of list bodies' left-margins.

.It Fl hang

.Fl tag ,

but instead of list bodies positioned after the head, they trail the

head text.

The

.Fl width

argument varies the width of list bodies' left-margins.

.It Fl hyphen

Synonym for

.Fl dash .

.It Fl inset

List bodies follow the list head.

The

.Fl width

argument is ignored.

.It Fl item

This produces blocks of text.

The head of list entries must be empty.

The

.Fl width

argument is ignored.

.It Fl ohang

List bodies are positioned on the line following the head.

The

.Fl width

argument is ignored.

.It Fl tag

A list offset by list entry heads. List entry bodies are positioned

after the head as specified by the

.Fl width

argument.

.El

.Pp

See also

.Sx \&It .

.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 1238 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 1295 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 1306 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 1319 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 1337 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 1365 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 1398 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

.D1 \. Ns Sx \&Dt Op Cm title Op Cm 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), defaulting to

required.

.Qq UNKNOWN

if unspecified.

It should be capitalised.

.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 1345 The manual section. This may be one of

Line 1449 The manual section. This may be one of

.Ar 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

This overrides the volume inferred from

.Ar section .

Line 1377 or

Line 1482 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 1415 Examples:

Line 1523 Examples:

.D1 \&.Dt FOO 1

.D1 \&.Dt FOO 4 KM

.D1 \&.Dt FOO 9 i386

.D1 \&.Dt FOO 9 KM i386

.Pp

See also

.Sx \&Dd

Line 1453 and

Line 1560 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 1587 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 1601 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 1534 and

Line 1643 and

.Ss \&Ic

.Ss \&In

.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

Specify a library.

The calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Lb Cm library

.Pp

The

.Cm library

parameter may be a system library, such as

.Cm libz

.Cm libpam ,

in which case a small library description is printed next to the linker

invocation; or a custom library, in which case the library name is

printed in quotes.

This is most commonly used in the

.Em SYNOPSIS

section as described in

.Sx MANUAL STRUCTURE .

.Pp

Examples:

.D1 \&.Lb libz

.D1 \&.Lb mdoc

.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 1550 See also

Line 1762 See also

.Ss \&Lp

.Ss \&Ms

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

.Ss \&No

Line 1575 and

Line 1796 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 1806 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 1854 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 1683 line.

Line 1907 line.

.Ss \&Sy

.Ss \&Tn

.Ss \&Ud

Prints out

.Dq currently under development.

.Ss \&Ux

Format the UNIX name. Accepts no argument.

Format the UNIX name.

Accepts no argument.

.Pp

Examples:

.D1 \&.Ux

Line 1700 and

Line 1927 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 1953 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 1967 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 1769 Heirloom troff, the other significant troff implementa

Line 1998 Heirloom troff, the other significant troff implementa

.Pp

.Bl -dash -compact

.It

groff does not accept the

.Sq \&Ta

pseudo-macro as a line macro.

mandoc does.

.It

The comment syntax

.Sq \e."

is no longer accepted.

Line 1776 is no longer accepted.

Line 2010 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 2043 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 2053 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 2071 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 ,

.Sx \&Ex ,

and

.Sx \&Ex

.Sx \&Rv

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.

.It

Newer groff and mandoc print

.Qq AT&T UNIX

prior to unknown arguments of

.Sx \&At ;

older groff did nothing.

.El

.Sh SEE ALSO

.Xr mandoc 1 ,

CVSweb