mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.87 and 1.120

version 1.87, 2010/03/31 07:13:53

version 1.120, 2010/06/06 10:49:56

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 MDOC 7

.Os

.Sh NAME

.Nm mdoc

.Nd mdoc language reference

.Sh DESCRIPTION

The

.Nm mdoc

Line 31 language is used to format

Line 27 language is used to format

.Bx

.Ux

manuals. In this reference document, we describe its syntax, structure,

and usage. Our reference implementation is

and usage. Our reference implementation is mandoc; the

.Xr mandoc 1 .

The

.Sx COMPATIBILITY

section describes compatibility with

section describes compatibility with other troff \-mdoc implementations.

.Xr groff 1 .

.Pp

.Nm

document follows simple rules: lines beginning with the control

character

.Sq \.

are parsed for macros. Other lines are interpreted within the scope of

Line 50 prior macros:

Line 42 prior macros:

\&.Sh Macro lines change control state.

Other lines are interpreted within the current state.

.Ed

.Sh LANGUAGE SYNTAX

.Nm

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

Line 59 character, and, in certain circumstances, the tab char

Line 49 character, and, in certain circumstances, the tab char

manuals must have

.Ux

line terminators.

.Ss Comments

Text following a

.Sq \e" ,

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

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

.Sq \&.\e" ,

is also ignored. Macro lines with only a control charater and optionally

whitespace are stripped from input.

.Ss Reserved Characters

Within a macro line, the following characters are reserved:

.Pp

Line 98 Within a macro line, the following characters are rese

Line 84 Within a macro line, the following characters are rese

.It \&|

.Pq vertical bar

.El

.Pp

Use of reserved characters is described in

.Sx MACRO SYNTAX .

Line 106 For general use in macro lines, these characters must

Line 91 For general use in macro lines, these characters must

with a non-breaking space

.Pq Sq \e&

or, if applicable, an appropriate escape sequence used.

.Ss Special Characters

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

Sequences begin with the escape character

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

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

.Sq \ee

.Pq back-slash .

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

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

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

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 175 Note these forms are

Line 160 Note these forms are

recommended for

.Nm ,

which encourages semantic annotation.

.Ss Predefined Strings

Historically,

.Xr groff 1

Line 195 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

.Sq \e*(Ba

.Pq vertical bar .

.Ss Whitespace

In non-literal free-form lines, consecutive blocks of whitespace are

Whitespace consists of the space character.

pruned from input and added later in the output filter, if applicable:

In free-form lines, whitespace is preserved within a line; un-escaped

.Bd -literal -offset indent

trailing spaces are stripped from input (unless in a literal context).

These spaces are pruned from input.

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

\&.Bd \-literal

within literal contexts.

These are not.

\&.Ed

.Ed

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

.Pp

Blank lines are only permitted within literal contexts, as are lines

containing only whitespace. Tab characters are only acceptable when

delimiting

.Sq \&Bl \-column

or when in a literal context.

.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 240 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"

.Ed

.Pp

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 275 Some examples of valid dates follow:

Line 244 Some examples of valid dates follow:

.D1 "May, 2009" Pq reduced form

.D1 "2009" Pq reduced form

.D1 "May 20, 2009" Pq canonical form

.Ss Scaling Widths

Many macros support scaled widths for their arguments, such as

stipulating a two-inch list indentation with the following:

.Bd -literal -offset indent

\&.Bl -tag -width 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

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 326 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 360 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

utility processes files ...

\&.\e\*q .Sh IMPLEMENTATION NOTES

\&.\e\*q The next is for sections 1 & 8 only.

\&.\e\*q .Sh EXIT STATUS

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

\&.\e\*q .Sh RETURN VALUES

\&.\e\*q The next is for sections 1, 6, 7, & 8 only.

\&.\e\*q .Sh ENVIRONMENT

\&.\e\*q .Sh FILES

\&.\e\*q The next is for sections 1 & 8 only.

\&.\e\*q .Sh EXIT STATUS

\&.\e\*q .Sh EXAMPLES

\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

\&.\e\*q .Sh DIAGNOSTICS

Line 401 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 424 See

Line 404 See

.Sx \&Nm

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

.Pp

See

.Sx \&Lb .

.It Em SYNOPSIS

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

configuration.

Line 479 See

Line 457 See

.Sx \&Ft ,

and

.Sx \&Vt .

.It Em DESCRIPTION

This expands upon the brief, one-line description in

.Em NAME .

Line 494 Print verbose information.

Line 471 Print verbose information.

.Ed

.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 EXIT STATUS

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

the dual of

.Em RETURN VALUES ,

which is used for functions. Historically, this information was

described in

.Em DIAGNOSTICS ,

a practise that is now discouraged.

.Pp

See

.Sx \&Ex .

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

.It Em ENVIRONMENT

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

.Xr environ 7 .

.Pp

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 the dual of

.Em RETURN VALUES ,

which is used for functions.

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 550 discouraged.

Line 522 discouraged.

See

.Sx \&Bl

.Fl diag .

.It Em ERRORS

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

.Pp

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

See

.Sx \&St .

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

.Pp

See

.Sx \&An .

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

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 621 parameters;

Line 584 parameters;

opens the scope of a macro; and if specified,

.Sq \&Yc

closes it out.

.Pp

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 .

.Pp

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 655 contains a head.

Line 615 contains a head.

\(lBbody...\(rB

\&.Yc

.Ed

.Pp

.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

Line 668 contains a head.

Line 627 contains a head.

.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk

.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl

.El

.Ss Block full-implicit

Multi-line scope closed by end-of-file or implicitly by another macro.

All macros have bodies; some

Line 689 has multiple heads.

Line 646 has multiple heads.

\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB

\(lBbody...\(rB

.Ed

.Pp

.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

Line 698 has multiple heads.

Line 654 has multiple heads.

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

.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 717 and/or tail

Line 671 and/or tail

\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \

\(lBbody...\(rB \&Yc \(lBtail...\(rB

.Ed

.Pp

.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

Line 746 and/or tail

Line 699 and/or tail

.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo

.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc

.El

.Ss Block partial-implicit

Like block full-implicit, but with single-line scope closed by

.Sx Reserved Characters

Line 755 or end of line.

Line 706 or end of line.

.Bd -literal -offset indent

\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB

.Ed

.Pp

.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable

Line 778 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 797 then the macro accepts an arbitrary number of argument

Line 747 then the macro accepts an arbitrary number of argument

\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN

.Ed

.Pp

.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments

Line 860 then the macro accepts an arbitrary number of argument

Line 809 then the macro accepts an arbitrary number of argument

.It Sx \&Ot Ta \&No Ta \&No Ta n

.It Sx \&Ox Ta Yes Ta Yes Ta n

.It Sx \&Pa Ta Yes Ta Yes Ta n

.It Sx \&Pf Ta \&No Ta Yes Ta 1

.It Sx \&Pf Ta Yes Ta Yes Ta 1

.It Sx \&Pp Ta \&No Ta \&No Ta 0

.It Sx \&Rv Ta \&No Ta \&No Ta n

.It Sx \&Sm Ta \&No Ta \&No Ta 1

Line 876 then the macro accepts an arbitrary number of argument

Line 825 then the macro accepts an arbitrary number of argument

.It Sx \&br Ta \&No Ta \&No Ta 0

.It Sx \&sp Ta \&No Ta \&No Ta 1

.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

.Sx \&Rs

Line 890 block. Multiple authors should each be accorded their

Line 837 block. Multiple authors should each be accorded their

.Sx \%%A

line. Author names should be ordered with full or abbreviated

forename(s) first, then full surname.

.Ss \&%B

Book title of an

.Sx \&Rs

block. This macro may also be used in a non-bibliographic context when

referring to book titles.

.Ss \&%C

Publication city or location of an

.Sx \&Rs

Line 905 block.

Line 850 block.

.Em Remarks :

this macro is not implemented in

.Xr groff 1 .

.Ss \&%D

Publication date of an

.Sx \&Rs

block. This should follow the reduced or canonical form syntax

described in

.Sx Dates .

.Ss \&%I

Publisher or issuer name of an

.Sx \&Rs

block.

.Ss \&%J

Journal name of an

.Sx \&Rs

block.

.Ss \&%N

Issue number (usually for journals) of an

.Sx \&Rs

block.

.Ss \&%O

Optional information of an

.Sx \&Rs

block.

.Ss \&%P

Book or journal page number of an

.Sx \&Rs

block.

.Ss \&%Q

Institutional author (school, government, etc.) of an

.Sx \&Rs

block. Multiple institutional authors should each be accorded their own

.Sx \&%Q

line.

.Ss \&%R

Technical report name of an

.Sx \&Rs

block.

.Ss \&%T

Article title of an

.Sx \&Rs

block. This macro may also be used in a non-bibliographical context

when referring to article titles.

.Ss \&%U

URI of reference document.

.Ss \&%V

Volume number of an

.Sx \&Rs

block.

.Ss \&Ac

Closes an

.Sx \&Ao

block. Does not have any tail arguments.

.Ss \&Ad

Address construct: usually in the context of an computational address in

memory, not a physical (post) address.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Ad [0,$]

\&.Ad [0,$]

.D1 \&.Ad 0x00000000

\&.Ad 0x00000000

.Ed

.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 992 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:

.Bd -literal -offset indent

.D1 \&.An -nosplit

\&.An -nosplit

.D1 \&.An J. D. Ullman .

\&.An J. E. Hopcraft ,

\&.An J. D. Ullman .

.Ed

.Pp

.Em Remarks :

the effects of

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

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

.Sx \&An Fl nosplit

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:

.Bd -literal -offset indent

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

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

.Ed

.Pp

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

.Ss \&Aq

Encloses its arguments in angled brackets.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Fl -key= \&Ns \&Aq \&Ar val

\&.Fl -key= Ns Aq Ar val

.Ed

.Pp

.Em Remarks :

this macro is often abused for rendering URIs, which should instead use

Line 1054 statements, which should use

Line 975 statements, which should use

.Pp

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

Examples:

.Bd -literal -offset indent

.D1 \&.Fl o \&Ns \&Ar file1

\&.Fl o Ns Ar file1

.D1 \&.Ar

\&.Ar

.D1 \&.Ar arg1 , arg2 .

\&.Ar arg1 , arg2 .

.Ed

.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 1081 A system version of

Line 1000 A system version of

Note that these parameters do not begin with a hyphen.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.At

\&.At

.D1 \&.At V.1

\&.At V.1

.Ed

.Pp

See also

.Sx \&Bsx ,

Line 1095 See also

Line 1012 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Bc

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 1123 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 1144 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 1179 See also

Line 1096 See also

.Sx \&D1

and

.Sx \&Dl .

.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

\&.Bo 1 ,

\&.Dv BUFSIZ Bc

\&.Dv BUFSIZ \&Bc

.Ed

.Pp

See also

.Sx \&Bq .

.Ss \&Bq

Encloses its arguments in square brackets.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Bq 1 , \&Dv BUFSIZ

\&.Bq 1 , Dv BUFSIZ

.Ed

.Pp

.Em Remarks :

this macro is sometimes abused to emulate optional arguments for

Line 1268 and

Line 1233 and

.Pp

See also

.Sx \&Bo .

.Ss \&Brc

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

\&.Bro 1 , ... ,

\&.Va n Brc

\&.Va n \&Brc

.Ed

.Pp

See also

.Sx \&Brq .

.Ss \&Brq

Encloses its arguments in curly braces.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Brq 1 , ... , \&Va n

\&.Brq 1 , ... , Va n

.Ed

.Pp

See also

.Sx \&Bro .

.Ss \&Bsx

Format the BSD/OS version provided as an argument, or a default value if

no argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Bsx 1.0

\&.Bsx 1.0

.D1 \&.Bsx

\&.Bsx

.Ed

.Pp

See also

.Sx \&At ,

Line 1317 See also

Line 1274 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Bt

Prints

.Dq is currently in beta test.

.Ss \&Bx

Format the BSD version provided as an argument, or a default value if no

argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Bx 4.4

\&.Bx 4.4

.D1 \&.Bx

\&.Bx

.Ed

.Pp

See also

.Sx \&At ,

Line 1341 See also

Line 1294 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Cd

Configuration declaration (suggested for use only in section four

Configuration declaration.

manuals). This denotes strings accepted by

This denotes strings accepted by

.Xr config 8 .

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Cd device le0 at scode?

\&.Cd device le0 at scode?

.Ed

.Pp

.Em Remarks :

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:

.Bd -literal -offset indent

.D1 \&.Cm ControlPath

\&.Cm ControlPath

.D1 \&.Cm ControlMaster

\&.Cm ControlMaster

.Ed

.Pp

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:

.Bd -literal -offset indent

.D1 \&.D1 \&Fl abcdefgh

\&.D1 Fl abcdefgh

.Ed

.Pp

See also

.Sx \&Bd

and

.Sx \&Dl .

.Ss \&Db

Start a debugging context.

This macro is parsed, but generally ignored.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Db Cm on | off

.Ss \&Dc

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 syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dd Cm date

.D1 Pf \. Sx \&Dd Cm date

.Pp

The

.Cm date

Line 1409 or instead a valid canonical date as specified by

Line 1361 or instead a valid canonical date as specified by

If a date does not conform, the current date is used instead.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Dd $\&Mdocdate$

\&.Dd $\&Mdocdate$

.D1 \&.Dd $\&Mdocdate: July 21 2007$

\&.Dd $\&Mdocdate: July 21 2007$

.D1 \&.Dd July 21, 2007

\&.Dd July 21, 2007

.Ed

.Pp

See also

.Sx \&Dt

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:

.Bd -literal -offset indent

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

\&.Dl % mandoc mdoc.7 | less

.Ed

.Pp

See also

.Sx \&Bd

and

.Sx \&D1 .

.Ss \&Do

Begins a block enclosed by double quotes. Does not have any head

arguments.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot

\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot

.Ed

.Pp

See also

.Sx \&Dq .

.Ss \&Dq

Encloses its arguments in double quotes.

.Pp

Examples:

.Bd -literal -offset indent

.Bd -literal -offset indent -compact

\&.Dq April is the cruellest month

\e(em T.S. Eliot

.Ed

.Pp

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 syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Dt

.Oo

.Cm title

.Oo

.Cm section

.Op Cm volume | arch

.Oc

.Ed

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

Line 1462 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 1537 or

Line 1495 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 1572 or

Line 1533 or

.El

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Dt FOO 1

\&.Dt FOO 1

.D1 \&.Dt FOO 4 KM

\&.Dt FOO 4 KM

.D1 \&.Dt FOO 9 i386

\&.Dt FOO 9 i386

\&.Dt FOO 9 KM i386

.Ed

.Pp

See also

.Sx \&Dd

and

.Sx \&Os .

.Ss \&Dv

Defined variables such as preprocessor constants.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Dv BUFSIZ

\&.Dv BUFSIZ

.D1 \&.Dv STDOUT_FILENO

\&.Dv STDOUT_FILENO

.Ed

.Pp

See also

.Sx \&Er .

.Ss \&Dx

Format the DragonFly BSD version provided as an argument, or a default

value if no argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Dx 2.4.1

\&.Dx 2.4.1

.D1 \&.Dx

\&.Dx

.Ed

.Pp

See also

.Sx \&At ,

Line 1615 See also

Line 1567 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Ec

.Ss \&Ed

.Ss \&Ef

.Ss \&Ek

.Ss \&El

Ends a list context started by

.Sx \&Bl .

.Pp

See also

.Sx \&Bl

and

.Sx \&It .

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

.Bd -literal -offset indent

.D1 \&.Em Warnings!

\&.Ed Warnings!

.D1 \&.Em Remarks :

\&.Ed Remarks :

.Ed

.Ss \&En

.Ss \&Eo

.Ss \&Er

Error constants (suggested for use only in section two manuals).

Display error constants.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Er EPERM

\&.Er EPERM

.D1 \&.Er ENOENT

\&.Er ENOENT

.Ed

.Pp

See also

.Sx \&Dv .

.Ss \&Es

.Ss \&Ev

Environmental variables such as those specified in

.Xr environ 7 .

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Ev DISPLAY

\&.Ev DISPLAY

.D1 \&.Ev PATH

\&.Ev PATH

.Ed

.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 1670 is not provided, the document's name as stipulated in

Line 1618 is not provided, the document's name as stipulated in

.Sx \&Nm

is provided.

.Ss \&Fa

Function argument.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Fa

.Op Cm argtype

.Cm argname

.Ed

.Pp

This may be invoked for names with or without the corresponding type.

It is also used to specify the field name of a structure.

Most often, the

.Sx \&Fa

macro is used in the

.Em SYNOPSIS

within

.Sx \&Fo

section when documenting multi-line function prototypes.

If invoked with multiple arguments, the arguments are separated by a

comma.

Furthermore, if the following macro is another

.Sx \&Fa ,

the last argument will also have a trailing comma.

.Pp

Examples:

.D1 \&.Fa \(dqconst char *p\(dq

.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq

.D1 \&.Fa foo

.Pp

See also

.Sx \&Fo .

.Ss \&Fc

.Ss \&Fd

Historically used to document include files.

This usage has been deprecated in favour of

.Sx \&In .

Do not use this macro.

.Pp

See also

.Sx \&In .

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

before each delimited argument. If no arguments are provided, a hyphen

directly followed by each argument.

is still printed.

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

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

output.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Fl a b c

\&.Fl a b c

.D1 \&.Fl \&Pf a b

\&.Fl

.D1 \&.Fl

\&.Op Fl o Ns Ar file

.D1 \&.Op \&Fl o \&Ns \&Ar file

.Ed

.Pp

See also

.Sx \&Cm .

.Ss \&Fn

A function name.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Ns Sx \&Fn

.Op Cm functype

.Cm funcname

.Op Oo Cm argtype Oc Cm argname

.Ed

.Pp

If invoked in the

.Em SYNOPSIS

section, vertical space is asserted before and after the macro.

In all cases, the function arguments are surrounded in parenthesis and

are delimited by commas.

If no arguments are specified, blank parenthesis are output.

.Pp

Examples:

.D1 \&.Fn "int funcname" "int arg0" "int arg1"

.D1 \&.Fn funcname "int arg0"

.D1 \&.Fn funcname arg0

.Bd -literal -offset indent -compact

\&.Ft functype

\&.Fn funcname

.Ed

.Pp

See also

.Sx \&Fa ,

.Sx \&Fo ,

.Sx \&Fc ,

and

.Sx \&Ft .

.Ss \&Fo

Begin a function block.

This is a multi-line version of

.Sx \&Fn .

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Fo Cm funcname

.Pp

Invocations usually occur in the following context:

.Bd -ragged -offset indent

.Pf \. Sx \&Ft Cm functype

.br

.Pf \. Sx \&Fo Cm funcname

.br

.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname

.br

\.\.\.

.br

.Pf \. Sx \&Fc

.Ed

.Pp

In the

.Em SYNOPSIS

section, a

.Sx \&Fo

block is surrounded by vertical space unless

.Sx \&Ft

is the prior macro, in which case it is preceded by only a newline.

.Pp

.Sx \&Fo

scope is closed by

.Pp

See also

.Sx \&Fa ,

.Sx \&Fc ,

and

.Sx \&Fn .

.Sx \&Fc .

.Ss \&Fr

.Ss \&Ft

A function type.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Ft Cm functype

.Pp

If invoked before a

.Sx \&Fo

.Sx \&Fn

in the

.Em SYNOPSIS

section, a line-break will follow.

Furthermore, if invoked in the

.Em SYNOPSIS

section, it will assert vertical space prior to its arguments.

.Pp

Examples:

.D1 \&.Ft int

.Bd -literal -offset indent -compact

\&.Ft functype

\&.Fn funcname

.Ed

.Pp

See also

.Sx \&Fo ,

.Sx \&Fc ,

and

.Sx \&Fn .

.Ss \&Fx

Format the FreeBSD version provided as an argument, or a default value

if no argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Fx 7.1

\&.Fx 7.1

.D1 \&.Fx

\&.Fx

.Ed

.Pp

See also

.Sx \&At ,

Line 1712 See also

Line 1793 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Hf

.Ss \&Ic

.Ss \&In

.Qq include

file.

In the

.Em SYNOPSIS

section (only if invoked as the line macro), the first argument is

preceded by

.Qq #include ,

the arguments is enclosed in angled braces, and a newline is asserted.

In all other invocations, only angled braces will enclose the argument.

.Pp

Examples

.D1 \&.In sys/types

.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 syntax:

.Pp

.D1 Pf \. Sx \&It Cm args

.Pp

Lists of type

.Fl bullet ,

.Fl dash ,

.Fl enum ,

.Fl hyphen

and

.Fl item

have the following syntax:

.Pp

.D1 Pf \. 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 the following syntax:

.Pp

.D1 Pf \. Sx \&It Op Cm args

.Pp

Subsequent lines are 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 as follows:

.Pp

.D1 Pf \. Sx \&It Op Cm args

.Pp

The

.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 syntax is as follows:

.Pp

.D1 Pf \. 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.

Its syntax is as follows:

.Pp

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

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

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Lk http://bsd.lv "The BSD.lv Project"

\&.Lk http://bsd.lv "The BSD.lv Project"

.D1 \&.Lk http://bsd.lv

\&.Lk http://bsd.lv

.Ed

.Pp

See also

.Sx \&Mt .

.Ss \&Lp

.Ss \&Ms

.Ss \&Mt

Format a

.Qq mailto:

hyperlink.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Mt Cm address

.Pp

Examples:

.D1 \&.Mt discuss@manpages.bsd.lv

.Ss \&Nd

.Ss \&Nm

.Ss \&No

Line 1745 Format the NetBSD version provided as an argument, or

Line 1948 Format the NetBSD version provided as an argument, or

no argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Nx 5.01

\&.Nx 5.01

.D1 \&.Nx

\&.Nx

.Ed

.Pp

See also

.Sx \&At ,

Line 1759 See also

Line 1960 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Oc

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

file.

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Os Op Cm system

.D1 Pf \. Sx \&Os Op Cm system

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

.Bd -literal -offset indent

.D1 \&.Os

\&.Os

.D1 \&.Os KTH/CSC/TCS

\&.Os KTH/CSC/TCS

.D1 \&.Os BSD 4.3

\&.Os BSD 4.3

.Ed

.Pp

See also

.Sx \&Dd

and

.Sx \&Dt .

.Ss \&Ot

Unknown usage.

.Pp

.Em Remarks :

this macro has been deprecated.

.Ss \&Ox

Format the OpenBSD version provided as an argument, or a default value

if no argument is provided.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Ox 4.5

\&.Ox 4.5

.D1 \&.Ox

\&.Ox

.Ed

.Pp

See also

.Sx \&At ,

Line 1814 See also

Line 2010 See also

.Sx \&Nx ,

and

.Sx \&Ux .

.Ss \&Pa

.Ss \&Pc

.Ss \&Pf

Line 1825 and

Line 2020 and

.Ss \&Ql

.Ss \&Qo

.Ss \&Qq

.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 1848 contain

Line 2043 contain

.Sx \&%Q ,

.Sx \&%R ,

.Sx \&%T ,

.Sx \&%U ,

and

.Sx \&%V

child macros (at least one must be specified).

.Pp

Examples:

.Bd -literal -offset indent

.Bd -literal -offset indent -compact

\&.Rs

\&.%A J. E. Hopcroft

\&.%A J. D. Ullman

Line 1869 If an

Line 2065 If an

block is used within a SEE ALSO section, a vertical space is asserted

before the rendered output, else the block continues on the current

line.

.Ss \&Rv

.Ss \&Sc

.Ss \&Sh

Line 1882 line.

Line 2077 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:

.Bd -literal -offset indent

.D1 \&.Ux

\&.Ux

.Ed

.Pp

See also

.Sx \&At ,

Line 1899 See also

Line 2095 See also

.Sx \&Nx ,

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 1916 Note that this should not be confused with

Line 2112 Note that this should not be confused with

which is used for function return types.

.Pp

Examples:

.Bd -literal -offset indent

.D1 \&.Vt unsigned char

\&.Vt unsigned char

.D1 \&.Vt extern const char * const sys_signame[] ;

\&.Vt extern const char * const sys_signame[] ;

.Ed

.Pp

See also

.Sx \&Ft

and

.Sx \&Va .

.Ss \&Xc

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 .

Its calling syntax is

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Xr Cm name section

.D1 Pf \. Sx \&Xr Cm name section

.Pp

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:

.Bd -literal -offset indent

.D1 \&.Xr mandoc 1

\&.Xr mandoc 1

.D1 \&.Xr mandoc 1 ;

\&.Xr mandoc 1 ;

.D1 \&.Xr mandoc 1 \&Ns s behaviour

\&.Xr mandoc 1 s behaviour

.Ed

.Ss \&br

.Ss \&sp

.Sh COMPATIBILITY

This section documents compatibility with other roff implementations, at

This section documents compatibility between mandoc and other other

this time limited to

troff implementations, at this time limited to GNU troff

.Xr groff 1 .

.Pq Qq groff .

The term

.Qq historic groff

refers to those versions before the

refers to groff versions before the

.Pa doc.tmac

file re-write

.Pq somewhere between 1.15 and 1.19 .

.Pp

Heirloom troff, the other significant troff implementation accepting

\-mdoc, is similar to historic groff.

.Pp

.Bl -dash -compact

.It

groff behaves inconsistently when encountering

.Pf non- Sx \&Fa

children of

.Sx \&Fo

regarding spacing between arguments.

In mandoc, this is not the case: each argument is consistently followed

by a single space and the trailing

.Sq \&)

suppresses prior spacing.

.It

groff behaves inconsistently when encountering

.Sx \&Ft

and

.Sx \&Fn

in the

.Em SYNOPSIS :

at times newline(s) are suppressed dependong on whether a prior

.Sx \&Fn

has been invoked.

In mandoc, this is not the case.

See

.Sx \&Ft

and

.Sx \&Fn

for the normalised behaviour.

.It

Historic groff does not break before an

.Sx \&Fn

when not invoked as the line macro in the

.Em SYNOPSIS

section.

.It

Historic groff formats the

.Sx \&In

badly: trailing arguments are trashed and

.Em SYNOPSIS

is not specially treated.

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

.It

In groff, the

.Xr groff 1 ,

the

.Sx \&Pa

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

certain list types. This irregular behaviour has been discontinued.

certain list types.

mandoc does.

.It

Historic

Historic groff does not print a dash for empty

.Xr groff 1

does not print a dash for empty

.Sx \&Fl

arguments. This behaviour has been discontinued.

arguments.

mandoc and newer groff implementations do.

.It

.Xr groff 1

groff behaves irregularly when specifying

behaves strangely (even between versions) when specifying

.Sq \ef

escapes within line-macro scopes. These aberrations have been

.Sx Text Decoration

normalised.

within line-macro scopes.

mandoc follows a consistent system.

.It

Negative scaling units are now truncated to zero instead of creating

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

interesting conditions, such as with

move to prior lines.

.Sx \&sp

.Fl 1i .

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 no longer applicable.

This idiosyncratic behaviour is not applicable in mandoc.

.It

Display types

.Sx \&Bd

Line 2020 Display types

Line 2248 Display types

and

.Fl right

are aliases for

.Fl left .

.Fl left

The

in manodc. Furthermore, the

.Fl file Ar file

argument is ignored. Since text is not right-justified,

argument is ignored.

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

.Fl ragged

and

.Fl filled

Line 2032 are aliases, as are

Line 2261 are aliases, as are

and

.Fl unfilled .

.It

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

Historic groff has many un-callable macros.

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

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

in free-form text lines.

.It

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

some block-level macros) are now callable, conforming to the

non-historic groff version.

.It

The vertical bar

.Sq \(ba

made historic groff

.Qq go orbital

but is a proper delimiter in this implementation.

but has been a proper delimiter since then.

.It

.Sx \&It

.Sx \&It Fl nested

.Fl nested

is assumed for all lists (it wasn't in historic groff): any list may be

nested and

.Fl enum

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

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

delimiter to render.

This is not supported in mandoc.

.It

In groff, the

.Sx \&Fo

.Sx \&Cd ,

macro only produces the first parameter. This is no longer the case.

.Sx \&Er ,

.Sx \&Ex ,

and

.Sx \&Rv

macros were stipulated only to occur in certain manual sections.

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 ,

.Xr mandoc_char 7

.Sh AUTHORS

The

.Nm

reference was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.An Kristaps Dzonsons Aq kristaps@bsd.lv .

.\"

.\" XXX: this really isn't the place for these caveats.

.\" .

CVSweb