mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.67 and 1.114

version 1.67, 2009/10/22 10:33:28

version 1.114, 2010/06/03 14:29:52

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

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

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

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

(Roman, or reset). This form is not recommended for

(revert to previous mode):

.Pp

.D1 \efBbold\efR \efIitalic\efP

.Pp

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

respectively) may be used instead.

A text decoration is 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.

.Sq \ef

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

text, it will affect the remainder of the document.

.Pp

Text may also be sized with the

.Sq \es

escape, whose syntax is one of

.Sq \es+-n

for one-digit numerals;

.Sq \es(+-nn

.Sq \es+-(nn

for two-digit numerals; and

.Sq \es[+-N] ,

.Sq \es+-[N] ,

.Sq \es'+-N' ,

.Sq \es+-'N'

for arbitrary-digit numerals:

.Pp

.D1 \es+1bigger\es-1

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

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

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

.Pp

Note these forms are

.Em not

recommended for

.Nm ,

which encourages semantic, not presentation, annotation.

which encourages semantic annotation.

.Ss Predefined Strings

Historically,

.Xr groff 1

also defined a set of package-specific

.Dq predefined strings ,

which, like

.Sx Special Characters ,

demark special output characters and strings by way of input codes.

Predefined strings are escaped with the slash-asterisk,

Line 155 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 200 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

that require a date argument.

.Em canonical form

The canonical form for dates is the American format:

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

The

Reduced form dates are broken-down canonical form dates:

.Em non-canonical form

is the same as the canonical form, but without the comma between the

.Cm Day

and

.Cm Year

field.

.Pp

Lastly,

.D1 Cm Month , Year

.Em reduced form

.D1 Cm Year

dates range from only a

.Cm Year

to the full canonical or non-canonical form.

.Pp

Some examples of valid dates follow:

.Pp

.D1 "May, 2009" Pq reduced form

.D1 "2009" Pq reduced form

.D1 "May 20, 2009" Pq canonical form

.D1 "May 20 2009" Pq non-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 297 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 314 and

Line 326 and

.Sx \&Os

macros, is required for every document.

.Pp

The first section (sections are denoted by

.Sx \&Sh )

must be the NAME section, consisting of at least one

.Sx \&Nm

Line 331 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 372 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 -tag -width Ds -offset Ds

.Bl -ohang -offset Ds

.It NAME

.It Em NAME

Must contain at least one

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

The syntax for this as follows:

.Bd -literal -offset indent

\&.Nm name0

\&.Nm name1

\&.Nm name2

\&.Nd a short description

.Ed

.Pp

The

.Sx \&Nm

followed by

macro(s) must precede the

.Sx \&Nd

macro.

.Pp

See

.Sx \&Nm

and

.Sx \&Nd .

The name needs re-stating since one

.It Em LIBRARY

.Nm

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

documents can be used for more than one utility or function, such as

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

.Xr grep 1

The syntax for this is as follows:

also being referenced as

.Bd -literal -offset indent

.Xr egrep 1

\&.Lb libarm

.Ed

.Pp

See

.Sx \&Lb .

.It Em SYNOPSIS

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

configuration.

.Pp

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

generally structured as follows:

.Bd -literal -offset indent

\&.Nm foo

\&.Op Fl v

\&.Op Fl o Ar file

\&.Op Ar

\&.Nm bar

\&.Op Fl v

\&.Op Fl o Ar file

\&.Op Ar

.Ed

.Pp

For the second, function calls (sections 2, 3, 9):

.Bd -literal -offset indent

\&.Vt extern const char *global;

\&.In header.h

\&.Ft "char *"

\&.Fn foo "const char *src"

\&.Ft "char *"

\&.Fn bar "const char *src"

.Ed

.Pp

And for the third, configurations (section 4):

.Bd -literal -offset indent

\&.Cd \*qit* at isa? port 0x2e\*q

\&.Cd \*qit* at isa? port 0x4e\*q

.Ed

.Pp

Manuals not in these sections generally don't need a

.Em SYNOPSIS .

.Pp

See

.Sx \&Op ,

.Sx \&Cd ,

.Sx \&Fn ,

.Sx \&Ft ,

and

.Xr fgrep 1 .

.Sx \&Vt .

.It LIBRARY

.It Em DESCRIPTION

.It SYNOPSIS

This expands upon the brief, one-line description in

.It DESCRIPTION

.Em NAME .

.It IMPLEMENTATION NOTES

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

.It EXIT STATUS

command), such as:

.It RETURN VALUES

.Bd -literal -offset indent

.It ENVIRONMENT

The arguments are as follows:

.It FILES

\&.Bl \-tag \-width Ds

.It EXAMPLES

\&.It Fl v

.It DIAGNOSTICS

Print verbose information.

.It ERRORS

\&.El

.It SEE ALSO

.Ed

.It STANDARDS

.Pp

.It HISTORY

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

.It AUTHORS

.It Em IMPLEMENTATION NOTES

.It CAVEATS

Implementation-specific notes should be kept here.

.It BUGS

This is useful when implementing standard functions that may have side

.It SECURITY CONSIDERATIONS

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 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 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, well-tested invocations.

Make doubly sure that your examples work properly!

.It Em DIAGNOSTICS

Documents error conditions.

This is most useful in section 4 manuals.

Historically, this section was used in place of

.Em EXIT STATUS

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

discouraged.

.Pp

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 for most manuals.

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 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 431 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 465 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 478 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 493 All macros have bodies; some

Line 640 All macros have bodies; some

don't have heads; only one

.Po

.Sx \&It Fl column

.Pc

has multiple heads.

.Bd -literal -offset indent

\&.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 508 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 527 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 556 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 565 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 580 or end of line.

Line 720 or end of line.

.It Sx \&Ql Ta Yes Ta Yes

.It Sx \&Qq Ta Yes Ta Yes

.It Sx \&Sq Ta Yes Ta Yes

.It Sx \&Vt Ta Yes Ta Yes

.El

.Pp

Note that the

.Sx \&Vt

macro is a

.Sx Block partial-implicit

only when invoked as the first macro

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 598 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 611 then the macro accepts an arbitrary number of argument

Line 759 then the macro accepts an arbitrary number of argument

.It Sx \&%N Ta \&No Ta \&No Ta >0

.It Sx \&%O Ta \&No Ta \&No Ta >0

.It Sx \&%P Ta \&No Ta \&No Ta >0

.It Sx \&%Q Ta \&No Ta \&No Ta >0

.It Sx \&%R Ta \&No Ta \&No Ta >0

.It Sx \&%T Ta \&No Ta \&No Ta >0

.It Sx \&%U Ta \&No Ta \&No Ta >0

.It Sx \&%V Ta \&No Ta \&No Ta >0

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

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

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

Line 821 then the macro accepts an arbitrary number of argument

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

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

.It Sx \&Vt Ta Yes Ta Yes Ta >0

.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3

.It Sx \&Xr Ta Yes Ta Yes Ta >0

.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 689 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 704 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 syntax for

block. This should follow the reduced or canonical form syntax

described in

.Sx Dates .

Canonical or non-canonical form is not necessary since publications are

often referenced only by year, or month and year.

.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 789 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 810 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 851 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 878 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 892 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 920 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 941 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 976 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 is associated with a type, which is a required argument.

Other arguments are

.Fl width ,

defined per-type as accepting a literal or

.Sx Scaling Widths

value;

.Fl offset ,

also accepting a literal or

.Sx Scaling Widths

value setting the list's global offset; and

.Fl compact ,

suppressing the default vertical space printed before each list entry.

A list entry is specified by the

.Sx \&It

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

type).

A list must specify one of the following list types:

.Bl -tag -width 12n -offset indent

.It Fl bullet

A list offset by a bullet.

The head of list entries must be empty.

List entry bodies are positioned after the bullet.

The

.Fl width

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

.It Fl column

A columnated list.

The

.Fl width

argument has no effect.

The number of columns is specified as parameters to the

.Sx \&Bl

macro.

These dictate the width of columns either as

.Sx Scaling Widths

or literal text.

If the initial macro of a

.Fl column

list is not an

.Sx \&It ,

.Sx \&It

context spanning each line is implied until an

.Sx \&It

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

described in the

.Sx \&It

documentation.

.It Fl dash

A list offset by a dash (hyphen).

The head of list entries must be empty.

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 1012 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 1061 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 1085 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

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

.Pp

.D1 \. Ns Sx \&Dd Cm date

.Pp

The

.Cm date

field may be either

.Ar $\&Mdocdate$ ,

which signifies the current manual revision date dictated by

.Xr cvs 1

.Xr cvs 1 ,

or instead a valid canonical date as specified by

.Sx Dates .

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 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 1248 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 1280 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 1296 subsequent that. It, too, is optional. It must be on

Line 1501 subsequent that. It, too, is optional. It must be on

.Ar hppa64 ,

.Ar i386 ,

.Ar landisk ,

.Ar loongson ,

.Ar luna88k ,

.Ar mac68k ,

.Ar macppc ,

Line 1314 or

Line 1520 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 DragonFlyBSD version provided as an argument, or a default

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 1357 See also

Line 1554 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Ec

.Ss \&Ed

.Ss \&Ef

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

.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 1415 is provided.

Line 1601 is provided.

.Ss \&Fc

.Ss \&Fd

.Ss \&Fl

Command-line flag.

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 printed followed by a space.

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

output.

.Pp

Examples:

.D1 \&.Fl a b c

.D1 \&.Fl \&Pf a b

.D1 \&.Fl

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

.Pp

See also

.Sx \&Cm .

.Ss \&Fn

.Ss \&Fo

.Ss \&Fr

Line 1424 Format the FreeBSD version provided as an argument, or

Line 1627 Format the FreeBSD version provided as an argument, or

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 1438 See also

Line 1639 See also

.Sx \&Ox ,

and

.Sx \&Ux .

.Ss \&Hf

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

.Pp

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

.Pp

Examples:

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

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

.Pp

See also

.Sx \&Mt .

.Ss \&Lp

.Ss \&Ms

.Ss \&Mt

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

Line 1771 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 1472 See also

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

Line 1486 file. Its calling syntax is as follows:

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

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

Line 1832 See also

.Sx \&Nx ,

and

.Sx \&Ux .

.Ss \&Pa

.Ss \&Pc

.Ss \&Pf

Line 1538 and

Line 1842 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 and may only

block.

contain

Does not have any head arguments.

The block macro may only contain

.Sx \&%A ,

.Sx \&%B ,

.Sx \&%C ,

Line 1566 and

Line 1870 and

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 1582 If an

Line 1886 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 1595 line.

Line 1898 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 1612 See also

Line 1916 See also

.Sx \&Nx ,

and

.Sx \&Ox .

.Ss \&Va

.Ss \&Vt

A variable type.

This is also used for indicating global variables in the SYNOPSIS

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

.Sx In-line

syntax.

.Pp

Note that this should not be confused with

.Sx \&Ft ,

which is used for function return types.

.Pp

Examples:

.D1 \&.Vt unsigned char

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

.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 9-argument limit of troff;

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

.Pp

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

.Pp

The

.Cm name

and

.Cm section

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 with

.Xr groff 1 .

.Pp

Examples:

.D1 \&.Xr mandoc 1

.D1 \&.Xr mandoc 1 ;

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

.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

Negative scaling units are now truncated to zero instead of creating

The comment syntax

interesting conditions, such as with

.Sq \e."

.Sq \&sp -1i .

is no longer accepted.

.It

In groff, the

.Sx \&Pa

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

certain list types.

mandoc does.

.It

Historic groff does not print a dash for empty

.Sx \&Fl

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.

.It

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

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

This idiosyncratic behaviour is not applicable in mandoc.

.It

Display types

.Sx \&Bd Fl center

.Sx \&Bd

.Fl center

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 1664 are aliases, as are

Line 2039 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 Fl nested

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

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

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

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

macro only produces the first parameter.

This is not the case in mandoc.

.It

In groff, the

.Sx \&Cd ,

.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