mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.118 and 1.139

version 1.118, 2010/06/04 21:49:39

version 1.139, 2010/07/19 15:43:10

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 26 The

Line 27 The

language is used to format

.Bx

.Ux

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

manuals.

and usage. Our reference implementation is mandoc; the

In this reference document, we describe its syntax, structure, and

usage.

Our reference implementation is mandoc; the

.Sx COMPATIBILITY

section describes compatibility with other troff \-mdoc implementations.

.Pp

Line 36 An

Line 39 An

document follows simple rules: lines beginning with the control

character

.Sq \.

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

are parsed for macros.

Other lines are interpreted within the scope of

prior macros:

.Bd -literal -offset indent

\&.Sh Macro lines change control state.

Line 45 Other lines are interpreted within the current state.

Line 49 Other lines are interpreted within the current state.

.Sh LANGUAGE SYNTAX

.Nm

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

character, and, in certain circumstances, the tab character. All

character, and, in certain circumstances, the tab character.

manuals must have

All manuals must have

.Ux

line terminators.

.Ss Comments

Text following a

.Sq \e" ,

.Sq \e\*q ,

whether in a macro or free-form text line, is ignored to the end of

line. A macro line with only a control character and comment escape,

line.

.Sq \&.\e" ,

A macro line with only a control character and comment escape,

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

.Sq \&.\e\*q ,

whitespace are stripped from input.

is also ignored.

Macro lines with only a control character and optionally whitespace are

stripped from input.

.Ss Reserved Characters

Within a macro line, the following characters are reserved:

.Pp

Line 134 If

Line 140 If

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

Note this form is

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

Line 167 also defined a set of package-specific

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

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

Predefined strings are escaped with the slash-asterisk,

.Sq \e* :

single-character

Line 333 must be the NAME section, consisting of at least one

Line 318 must be the NAME section, consisting of at least one

followed by

.Sx \&Nd .

.Pp

Following that, convention dictates specifying at least the SYNOPSIS and

Following that, convention dictates specifying at least the

DESCRIPTION sections, although this varies between manual sections.

.Em SYNOPSIS

and

.Em DESCRIPTION

sections, although this varies between manual sections.

.Pp

The following is a well-formed skeleton

.Nm

Line 450 And for the third, configurations (section 4):

Line 438 And for the third, configurations (section 4):

Manuals not in these sections generally don't need a

.Em SYNOPSIS .

.Pp

See

Some macros are displayed differently in the

.Sx \&Op ,

.Em SYNOPSIS

section, particularly

.Sx \&Nm ,

.Sx \&Cd ,

.Sx \&Fd ,

.Sx \&Fn ,

.Sx \&Ft ,

.Sx \&Fo ,

.Sx \&In ,

.Sx \&Vt ,

and

.Sx \&Vt .

.Sx \&Ft .

All of these macros are output on their own line.

If two such dissimilar macros are pair-wise invoked (except for

.Sx \&Ft

before

.Sx \&Fo

.Sx \&Fn ) ,

they are separated by a vertical space, unless in the case of

.Sx \&Fo ,

.Sx \&Fn ,

and

.Sx \&Ft ,

which are always separated by vertical space.

.Pp

When text and macros following an

.Sx \&Nm

macro starting an input line span multiple output lines,

all output lines but the first will be indented to align

with the text immediately following the

.Sx \&Nm

macro, up to the next

.Sx \&Nm ,

.Sx \&Sx ,

.Sx \&Ss

macro or the end of an enclosing block, whichever comes first.

.It Em DESCRIPTION

This expands upon the brief, one-line description in

.Em NAME .

Line 651 has multiple heads.

Line 670 has multiple heads.

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

.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El

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

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

.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

.Pp

Note that the

.Sx \&Nm

macro is a

.Sx Block full-implicit

macro only when invoked as the first macro

in a

.Em SYNOPSIS

section line, else it is

.Sx In-line .

.Ss Block partial-explicit

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

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

Line 833 For the scoping of individual macros, see

Line 863 For the scoping of individual macros, see

.Ss \&%A

Author name of an

.Sx \&Rs

block. Multiple authors should each be accorded their own

block.

Multiple authors should each be accorded their own

.Sx \%%A

line. Author names should be ordered with full or abbreviated

line.

forename(s) first, then full surname.

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

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

Line 853 this macro is not implemented in

Line 886 this macro is not implemented in

.Ss \&%D

Publication date of an

.Sx \&Rs

block. This should follow the reduced or canonical form syntax

block.

described in

This should follow the reduced or canonical form syntax described in

.Sx Dates .

.Ss \&%I

Publisher or issuer name of an

Line 879 block.

Line 912 block.

.Ss \&%Q

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

.Sx \&Rs

block. Multiple institutional authors should each be accorded their own

block.

Multiple institutional authors should each be accorded their own

.Sx \&%Q

line.

.Ss \&%R

Line 889 block.

Line 923 block.

.Ss \&%T

Article title of an

.Sx \&Rs

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

block.

when referring to article titles.

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

referring to article titles.

.Ss \&%U

URI of reference document.

.Ss \&%V

Line 900 block.

Line 935 block.

.Ss \&Ac

Closes an

.Sx \&Ao

block. Does not have any tail arguments.

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.

Line 951 Examples:

Line 987 Examples:

See also

.Sx \&Aq .

.Ss \&Ap

Inserts an apostrophe without any surrounding white-space.

Inserts an apostrophe without any surrounding whitespace.

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

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

form of a function:

.Bd -literal -offset indent

\&.Fn execve Ap d

Line 1015 and

Line 1051 and

.Ss \&Bc

Closes a

.Sx \&Bo

block. Does not have any tail arguments.

block.

Does not have any tail arguments.

.Ss \&Bd

Begins a display block.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Bd

.Fl type

.Op Fl offset Ar width

.Op Fl compact

.Ed

.Pp

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

offset or justified in a manner different from that

of the enclosing context.

Line 1042 Centre-justify each line.

Line 1087 Centre-justify each line.

The type must be provided first.

Secondary arguments are as follows:

.Bl -tag -width 12n -offset indent

.It Fl offset Ar width

.It Fl offset Ar val

Offset by the value of

.Ar width ,

.Ar val ,

which is interpreted as one of the following, specified in order:

.Bl -item

.It

Line 1055 the width of standard indentation;

Line 1100 the width of standard indentation;

twice

.Ar indent ;

.Ar left ,

which has no effect ;

which has no effect;

.Ar right ,

which justifies to the right margin; and

.Ar center ,

Line 1073 As a scaling unit following the syntax described in

Line 1118 As a scaling unit following the syntax described in

As the calculated string length of the opaque string.

.El

.Pp

If unset, it will revert to the value of

If not provided an argument, it will be ignored.

.Ar 8n

as described in

.Sx Scaling Widths .

.It Fl compact

Do not assert a vertical space before the block.

.It Fl file Ar file

Prepend the file

.Ar file

before any text or macros within the block.

.El

.Pp

Examples:

Line 1097 See also

Line 1135 See also

and

.Sx \&Dl .

.Ss \&Bf

Change the font mode for a scoped block of text.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Bf

.Oo

.Fl emphasis | literal | symbolic |

.Cm \&Em | \&Li | \&Sy

.Oc

.Ed

.Pp

The

.Fl emphasis

and

.Cm \&Em

argument are equivalent, as are

.Fl symbolic

and

.Cm \&Sy,

and

.Fl literal

and

.Cm \&Li .

Without an argument, this macro does nothing.

The font mode continues until broken by a new font mode in a nested

scope or

.Sx \&Ef

is encountered.

.Pp

See also

.Sx \&Li ,

.Sx \&Ef ,

and

.Sx \&Sy .

.Ss \&Bk

Begins a collection of macros or text not breaking the line.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Bk Fl words

.Pp

Subsequent arguments are ignored.

The

.Fl words

argument is required.

.Pp

Each line within a keep block is kept intact, so the following example

will not break within each

.Sx \&Op

macro line:

.Bd -literal -offset indent

\&.Bk \-words

\&.Op Fl f Ar flags

\&.Op Fl o Ar output

\&.Ek

.Ed

.Pp

Be careful in using over-long lines within a keep block!

Doing so will clobber the right margin.

.Ss \&Bl

Begins a list composed of one or more list entries.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Bl

.Fl type

.Op Fl width Ar val

.Op Fl offset Ar val

.Op Fl compact

.Op HEAD ...

.Ed

.Pp

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

Other arguments are

.Fl width ,

Line 1197 The

Line 1301 The

.Fl width

argument is ignored.

.It Fl tag

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

A list offset by list entry heads.

after the head as specified by the

List entry bodies are positioned after the head as specified by the

.Fl width

argument.

.El

Line 1236 See also

Line 1340 See also

.Ss \&Brc

Closes a

.Sx \&Bro

block. Does not have any tail arguments.

block.

Does not have any tail arguments.

.Ss \&Bro

Begins a block enclosed by curly braces.

Does not have any head arguments.

Line 1304 Examples:

Line 1409 Examples:

.Pp

.Em Remarks :

this macro is commonly abused by using quoted literals to retain

white-space and align consecutive

whitespace and align consecutive

.Sx \&Cd

declarations.

This practise is discouraged.

Line 1334 and

Line 1439 and

.Ss \&Db

Start a debugging context.

This macro is parsed, but generally ignored.

Its calling syntax is as follows:

Its syntax is as follows:

.Pp

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

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

.Ss \&Dc

Closes a

.Sx \&Do

block. Does not have any tail arguments.

block.

Does not have any tail arguments.

.Ss \&Dd

Document date.

This is the mandatory first macro of any

.Nm

manual.

Its calling syntax is as follows:

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dd Cm date

.D1 Pf \. Sx \&Dd Cm date

.Pp

The

.Cm date

Line 1383 See also

Line 1489 See also

and

.Sx \&D1 .

.Ss \&Do

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

Begins a block enclosed by double quotes.

arguments.

Does not have any head arguments.

.Pp

Examples:

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

Line 1392 Examples:

Line 1498 Examples:

See also

.Sx \&Dq .

.Ss \&Dq

Encloses its arguments in double quotes.

Encloses its arguments in

.Dq typographic

double-quotes.

.Pp

Examples:

.Bd -literal -offset indent -compact

Line 1401 Examples:

Line 1509 Examples:

.Ed

.Pp

See also

.Sx \&Qq ,

.Sx \&Sq ,

and

.Sx \&Do .

.Ss \&Dt

Document title.

This is the mandatory second macro of any

.Nm

file.

Its calling syntax is as follows:

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 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), defaulting to

.Qq UNKNOWN

.Dq UNKNOWN

if unspecified.

It should be capitalised.

.It Cm section

Line 1455 or

Line 1574 or

.Ar paper

.Pq paper .

It should correspond to the manual's filename suffix and defaults to

.Qq 1

.Dq 1

if unspecified.

.It Cm volume

This overrides the volume inferred from

Line 1560 See also

Line 1679 See also

and

.Sx \&Ux .

.Ss \&Ec

Close a scope started by

.Sx \&Eo .

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Ec Op Cm TERM

.Pp

The

.Cm TERM

argument is used as the enclosure tail, for example, specifying \e(rq

will emulate

.Sx \&Dc .

.Ss \&Ed

End a display context started by

.Sx \&Bd .

.Ss \&Ef

Ends a font mode context started by

.Sx \&Bf .

.Ss \&Ek

Ends a keep context started by

.Sx \&Bk .

.Ss \&El

Ends a list context started by

.Sx \&Bl .

Line 1579 stylistically decorating technical terms.

Line 1715 stylistically decorating technical terms.

Examples:

.D1 \&.Em Warnings!

.D1 \&.Em Remarks :

.Pp

See also

.Sx \&Bf ,

.Sx \&Sy ,

and

.Sx \&Li .

.Ss \&En

This macro is obsolete and not implemented.

.Ss \&Eo

An arbitrary enclosure.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Eo Op Cm TERM

.Pp

The

.Cm TERM

argument is used as the enclosure head, for example, specifying \e(lq

will emulate

.Sx \&Do .

.Ss \&Er

Display error constants.

.Pp

Line 1591 Examples:

Line 1744 Examples:

See also

.Sx \&Dv .

.Ss \&Es

This macro is obsolete and not implemented.

.Ss \&Ev

Environmental variables such as those specified in

.Xr environ 7 .

Line 1599 Examples:

Line 1753 Examples:

.D1 \&.Ev DISPLAY

.D1 \&.Ev PATH

.Ss \&Ex

Inserts text regarding a utility's exit values.

Inserts text regarding a utility's exit value.

This macro must have first the

This macro must consist of the

.Fl std

argument specified, then an optional

argument followed by an optional

.Ar utility .

.Ar utility

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

.Sx \&Nm

is provided.

.Pp

See also

.Sx \&Rv .

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

Line 1628 Examples:

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

Ends a function context started by

.Sx \&Fo .

.Ss \&Fd

Historically used to document include files.

This usage has been deprecated in favour of

Line 1636 This usage has been deprecated in favour of

Line 1807 This usage has been deprecated in favour of

Do not use this macro.

.Pp

See also

.Sx MANUAL STRUCTURE

and

.Sx \&In .

.Ss \&Fl

Command-line flag.

Line 1656 Examples:

Line 1829 Examples:

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

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 MANUAL STRUCTURE

and

.Sx \&Ft .

.Ss \&Fo

.Ss \&Fr

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

.Sx \&Fo

scope is closed by

.Pp

See also

.Sx MANUAL STRUCTURE ,

.Sx \&Fa ,

.Sx \&Fc ,

and

.Sx \&Ft .

.Ss \&Ft

A function type.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Ft Cm functype

.Pp

Examples:

.D1 \&.Ft int

.Bd -literal -offset indent -compact

\&.Ft functype

\&.Fn funcname

.Ed

.Pp

See also

.Sx MANUAL STRUCTURE ,

.Sx \&Fn ,

and

.Sx \&Fo .

.Ss \&Fx

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

if no argument is provided.

Line 1677 See also

Line 1922 See also

and

.Sx \&Ux .

.Ss \&Hf

This macro is obsolete and not implemented.

.Ss \&Ic

Designate an internal or interactive command.

This is similar to

.Sx \&Cm

but used for instructions rather than values.

.Pp

Examples:

.D1 \&.Ic hash

.D1 \&.Ic alias

.Pp

Note that using

.Sx \&Bd No Fl literal

.Sx \&D1

is preferred for displaying code; the

.Sx \&Ic

macro is used when referring to specific instructions.

.Ss \&In

.Qq include

.Dq include

file.

In the

.Em SYNOPSIS

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

preceded by

.Qq #include ,

.Dq #include ,

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

the arguments is enclosed in angled braces.

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

.Pp

Examples

Examples:

.D1 \&.In sys/types

.Pp

See also

.Sx MANUAL STRUCTURE .

.Ss \&It

A list item. The syntax of this macro depends on the list type.

A list item.

The syntax of this macro depends on the list type.

.Pp

Lists

of type

Line 1702 of type

Line 1967 of type

.Fl inset ,

and

.Fl diag

have the following calling syntax:

have the following syntax:

.Pp

.D1 \. Ns Sx \&It Cm args

.D1 Pf \. Sx \&It Cm args

.Pp

Lists of type

.Fl bullet ,

Line 1713 Lists of type

Line 1978 Lists of type

.Fl hyphen

and

.Fl item

have the following calling syntax:

have the following syntax:

.Pp

.D1 \. Ns Sx \&It

.D1 Pf \. Sx \&It

.Pp

with subsequent lines interpreted within the scope of the

.Sx \&It

Line 1726 or another

Line 1991 or another

.Pp

The

.Fl tag

list has syntax

list has the following syntax:

.Pp

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

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

.Pp

with subsequent lines interpreted as with

Subsequent lines are interpreted as with

.Fl bullet

and family.

The line arguments correspond to the list's left-hand side; body

Line 1739 arguments correspond to the list's contents.

Line 2004 arguments correspond to the list's contents.

The

.Fl column

list is the most complicated.

Its syntax is

Its syntax is as follows:

.Pp

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

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

.Pp

where

The

.Cm args

are phrases, a mix of macros and text corresponding to a line column,

delimited by tabs or the special

Line 1755 are interpreted within the scope of the last phrase.

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

interpreted as a macro).

used within the

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

Furthermore, note that quoted sections propagate over tab-delimited

phrases on an

.Sx \&It ,

for example,

.Pp

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;

.Pp

will preserve the semicolon whitespace except for the last.

.Pp

Line 1775 See also

Line 2040 See also

.Sx \&Bl .

.Ss \&Lb

Specify a library.

The calling syntax is as follows:

The syntax is as follows:

.Pp

.D1 \. Ns Sx \&Lb Cm library

.D1 Pf \. Sx \&Lb Cm library

.Pp

The

.Cm library

Line 1797 Examples:

Line 2062 Examples:

.D1 \&.Lb libz

.D1 \&.Lb mdoc

.Ss \&Li

Denotes text that should be in a literal font mode.

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

stylistically decorating technical terms.

.Pp

See also

.Sx \&Bf ,

.Sx \&Sy ,

and

.Sx \&Em .

.Ss \&Lk

Format a hyperlink.

The calling syntax is as follows:

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:

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

Line 1810 Examples:

Line 2084 Examples:

See also

.Sx \&Mt .

.Ss \&Lp

Synonym for

.Sx \&Pp .

.Ss \&Ms

Display a mathematical symbol.

.Pp

Examples:

.D1 \&.Ms sigma

.D1 \&.Ms aleph

.Ss \&Mt

Format a

.Qq mailto:

.Dq mailto:

hyperlink.

The calling syntax is as follows:

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Mt Cm address

.D1 Pf \. Sx \&Mt Cm address

.Pp

Examples:

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

.Ss \&Nd

A one-line description of the manual's content.

This may only be invoked in the

.Em SYNOPSIS

section subsequent the

.Sx \&Nm

macro.

.Pp

Examples:

.D1 \&.Sx \&Nd mdoc language reference

.D1 \&.Sx \&Nd format and display UNIX manuals

.Pp

The

.Sx \&Nd

macro technically accepts child macros and terminates with a subsequent

.Sx \&Sh

invocation.

Do not assume this behaviour: some

.Xr whatis 1

database generators are not smart enough to parse more than the line

arguments and will display macros verbatim.

.Pp

See also

.Sx \&Nm .

.Ss \&Nm

The name of the manual page, or \(em in particular in section 1, 6,

and 8 pages \(em of an additional command or feature documented in

the manual page.

When first invoked, the

.Sx \&Nm

macro expects a single argument, the name of the manual page.

Usually, the first invocation happens in the

.Em NAME

section of the page.

The specified name will be remembered and used whenever the macro is

called again without arguments later in the page.

The

.Sx \&Nm

macro uses

.Sx Block full-implicit

semantics when invoked as the first macro on an input line in the

.Em SYNOPSIS

section; otherwise, it uses ordinary

.Sx In-line

semantics.

.Pp

Examples:

.Bd -literal -offset indent

\&.Sh SYNOPSIS

\&.Nm cat

\&.Op Fl benstuv

\&.Op Ar

.Ed

.Pp

In the

.Em SYNOPSIS

of section 2, 3 and 9 manual pages, use the

.Sx \&Fn

macro rather than

.Sx \&Nm

to mark up the name of the manual page.

.Ss \&No

.Dq noop

macro used to terminate prior macro contexts.

.Pp

Examples:

.D1 \&.Sx \&Fl ab \&No cd \&Fl ef

.Ss \&Ns

Suppress a space.

Following invocation, text is interpreted as free-form text until a

macro is encountered.

.Pp

Examples:

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

.Pp

See also

.Sx \&No

and

.Sx \&Sm .

.Ss \&Nx

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

no argument is provided.

Line 1843 See also

Line 2200 See also

and

.Sx \&Ux .

.Ss \&Oc

Closes multi-line

.Sx \&Oo

context.

.Ss \&Oo

Multi-line version of

.Sx \&Op .

.Pp

Examples:

.Bd -literal -offset indent -compact

\&.Oo

\&.Op Fl flag Ns Ar value

\&.Oc

.Ed

.Ss \&Op

Command-line option.

Used when listing options to command-line utilities.

Prints the argument(s) in brackets.

.Pp

Examples:

.D1 \&.Op \&Fl a \&Ar b

.D1 \&.Op \&Ar a | b

.Pp

See also

.Sx \&Oo .

.Ss \&Os

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

Line 1892 See also

Line 2272 See also

and

.Sx \&Ux .

.Ss \&Pa

A file-system path.

.Pp

Examples:

.D1 \&.Pa /usr/bin/mandoc

.D1 \&.Pa /usr/share/man/man7/mdoc.7

.Pp

See also

.Sx \&Lk .

.Ss \&Pc

Close parenthesised context opened by

.Sx \&Po .

.Ss \&Pf

Removes the space

.Pq Dq prefix

between its arguments.

Its syntax is as follows:

.Pp

.D1 Pf \. \&Pf Cm prefix suffix

.Pp

The

.Cm suffix

argument may be a macro.

.Pp

Examples:

.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix

.Ss \&Po

Multi-line version of

.Sx \&Pq .

.Ss \&Pp

Break a paragraph.

This will assert vertical space between prior and subsequent macros

and/or text.

.Ss \&Pq

Parenthesised enclosure.

.Pp

See also

.Sx \&Po .

.Ss \&Qc

Close quoted context opened by

.Sx \&Qo .

.Ss \&Ql

Format a single-quoted literal.

See also

.Sx \&Qq

and

.Sx \&Sq .

.Ss \&Qo

Multi-line version of

.Sx \&Qq .

.Ss \&Qq

Encloses its arguments in

.Dq typewriter

double-quotes.

Consider using

.Sx \&Dq .

.Pp

See also

.Sx \&Dq ,

.Sx \&Sq ,

and

.Sx \&Qo .

.Ss \&Re

Closes a

.Sx \&Rs

Line 1924 The block macro may only contain

Line 2356 The block macro may only contain

.Sx \&%Q ,

.Sx \&%R ,

.Sx \&%T ,

.Sx \&%U ,

and

.Sx \&%V

child macros (at least one must be specified).

Line 1946 block is used within a SEE ALSO section, a vertical sp

Line 2379 block is used within a SEE ALSO section, a vertical sp

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

line.

.Ss \&Rv

Inserts text regarding a function call's return value.

This macro must consist of the

.Fl std

argument followed by an optional

.Ar function .

.Ar function

is not provided, the document's name as stipulated by the first

.Sx \&Nm

is provided.

.Pp

See also

.Sx \&Ex .

.Ss \&Sc

Close single-quoted context opened by

.Sx \&So .

.Ss \&Sh

Begin a new section.

For a list of conventional manual sections, see

.Sx MANUAL STRUCTURE .

These sections should be used unless it's absolutely necessary that

custom sections be used.

.Pp

Section names should be unique so that they may be keyed by

.Sx \&Sx .

.Pp

See also

.Sx \&Pp ,

.Sx \&Ss ,

and

.Sx \&Sx .

.Ss \&Sm

Switches the spacing mode for output generated from macros.

Its syntax is as follows:

.Pp

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

.Pp

By default, spacing is

.Cm on .

When switched

.Cm off ,

no white space is inserted between macro arguments and between the

output generated from adjacent macros, but free-form text lines

still get normal spacing between words and sentences.

.Ss \&So

Multi-line version of

.Sx \&Sq .

.Ss \&Sq

Encloses its arguments in

.Dq typewriter

single-quotes.

.Pp

See also

.Sx \&Dq ,

.Sx \&Qq ,

and

.Sx \&So .

.Ss \&Ss

Begin a new sub-section.

Unlike with

.Sx \&Sh ,

there's no convention for sub-sections.

Conventional sections, as described in

.Sx MANUAL STRUCTURE ,

rarely have sub-sections.

.Pp

Sub-section names should be unique so that they may be keyed by

.Sx \&Sx .

.Pp

See also

.Sx \&Pp ,

.Sx \&Sh ,

and

.Sx \&Sx .

.Ss \&St

Replace an abbreviation for a standard with the full form.

The following standards are recognised:

.Pp

.Bl -tag -width "-p1003.1g-2000X" -compact

.It \-p1003.1-88

.St -p1003.1-88

.It \-p1003.1-90

.St -p1003.1-90

.It \-p1003.1-96

.St -p1003.1-96

.It \-p1003.1-2001

.St -p1003.1-2001

.It \-p1003.1-2004

.St -p1003.1-2004

.It \-p1003.1-2008

.St -p1003.1-2008

.It \-p1003.1

.St -p1003.1

.It \-p1003.1b

.St -p1003.1b

.It \-p1003.1b-93

.St -p1003.1b-93

.It \-p1003.1c-95

.St -p1003.1c-95

.It \-p1003.1g-2000

.St -p1003.1g-2000

.It \-p1003.1i-95

.St -p1003.1i-95

.It \-p1003.2-92

.St -p1003.2-92

.It \-p1003.2a-92

.St -p1003.2a-92

.It \-p1387.2-95

.St -p1387.2-95

.It \-p1003.2

.St -p1003.2

.It \-p1387.2

.St -p1387.2

.It \-isoC

.St -isoC

.It \-isoC-90

.St -isoC-90

.It \-isoC-amd1

.St -isoC-amd1

.It \-isoC-tcor1

.St -isoC-tcor1

.It \-isoC-tcor2

.St -isoC-tcor2

.It \-isoC-99

.St -isoC-99

.It \-iso9945-1-90

.St -iso9945-1-90

.It \-iso9945-1-96

.St -iso9945-1-96

.It \-iso9945-2-93

.St -iso9945-2-93

.It \-ansiC

.St -ansiC

.It \-ansiC-89

.St -ansiC-89

.It \-ansiC-99

.St -ansiC-99

.It \-ieee754

.St -ieee754

.It \-iso8802-3

.St -iso8802-3

.It \-ieee1275-94

.St -ieee1275-94

.It \-xpg3

.St -xpg3

.It \-xpg4

.St -xpg4

.It \-xpg4.2

.St -xpg4.2

.St -xpg4.3

.It \-xbd5

.St -xbd5

.It \-xcu5

.St -xcu5

.It \-xsh5

.St -xsh5

.It \-xns5

.St -xns5

.It \-xns5.2

.St -xns5.2

.It \-xns5.2d2.0

.St -xns5.2d2.0

.It \-xcurses4.2

.St -xcurses4.2

.It \-susv2

.St -susv2

.It \-susv3

.St -susv3

.It \-svid4

.St -svid4

.El

.Ss \&Sx

Reference a section or sub-section.

The referenced section or sub-section name must be identical to the

enclosed argument, including whitespace.

.Pp

Examples:

.D1 \&.Sx MANUAL STRUCTURE

.Ss \&Sy

Format enclosed arguments in symbolic

.Pq Dq boldface .

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

stylistically decorating technical terms.

.Pp

See also

.Sx \&Bf ,

.Sx \&Li ,

and

.Sx \&Em .

.Ss \&Tn

Format a tradename.

.Pp

Examples:

.D1 \&.Tn IBM

.Ss \&Ud

Prints out

.Dq currently under development.

Line 1976 See also

Line 2593 See also

and

.Sx \&Ox .

.Ss \&Va

A variable name.

.Pp

Examples:

.D1 \&.Va foo

.D1 \&.Va const char *bar ;

.Ss \&Vt

A variable type.

This is also used for indicating global variables in the SYNOPSIS

This is also used for indicating global variables in the

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

syntax when invoked as the first macro in the

accepts ordinary

.Em SYNOPSIS

section, else it accepts ordinary

.Sx In-line

syntax.

.Pp

Line 1993 which is used for function return types.

Line 2617 which is used for function return types.

.Pp

Examples:

.D1 \&.Vt unsigned char

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

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

.Pp

See also

.Sx \&Ft

.Sx MANUAL STRUCTURE

and

.Sx \&Va .

.Ss \&Xc

Line 2009 since this limit has been lifted, the macro has been d

Line 2633 since this limit has been lifted, the macro has been d

.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

Line 2028 This behaviour is for compatibility with

Line 2652 This behaviour is for compatibility with

.Pp

Examples:

.D1 \&.Xr mandoc 1

.D1 \&.Xr mandoc 1 ;

.D1 \&.Xr mandoc 1 \&;

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

.Ss \&br

.Ss \&sp

Line 2048 Heirloom troff, the other significant troff implementa

Line 2672 Heirloom troff, the other significant troff implementa

.Pp

.Bl -dash -compact

.It

The \es (font size), \em (font colour), and \eM (font filling colour)

font decoration escapes are all discarded in mandoc.

.It

Old groff fails to assert a newline before

.Sx \&Bd Fl ragged 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 depending 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

Line 2060 pseudo-macro as a line macro.

Line 2722 pseudo-macro as a line macro.

mandoc does.

.It

The comment syntax

.Sq \e."

.Sq \e\."

is no longer accepted.

.It

In groff, the

Line 2090 In quoted literals, groff allowed pair-wise double-quo

Line 2752 In quoted literals, groff allowed pair-wise double-quo

standalone double-quote in formatted output.

This idiosyncratic behaviour is not applicable in mandoc.

.It

Display types

Display offsets

.Sx \&Bd

.Fl center

.Fl offset Ar center

and

.Fl right

.Fl offset Ar right

are aliases for

are disregarded in mandoc.

.Fl left

Furthermore, troff specifies a

in manodc. Furthermore, the

.Fl file Ar file

argument is ignored.

argument that is not supported in mandoc.

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

.Fl ragged

and

Line 2131 delimiter to render.

Line 2792 delimiter to render.

This is not supported in mandoc.

.It

In groff, the

.Sx \&Fo

macro only produces the first parameter.

This is not the case in mandoc.

.It

In groff, the

.Sx \&Cd ,

.Sx \&Er ,

.Sx \&Ex ,

Line 2158 The

Line 2814 The

.Nm

reference was written by

.An Kristaps Dzonsons Aq kristaps@bsd.lv .

.\"

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

.\" .

.\" .Sh CAVEATS

.\" There are many ambiguous parts of mdoc.

.\" .

.\" .Pp

.\" .Bl -dash -compact

.\" .It

.\" .Sq \&Fa

.\" should be

.\" .Sq \&Va

.\" as function arguments are variables.

.\" .It

.\" .Sq \&Ft

.\" should be

.\" .Sq \&Vt

.\" as function return types are still types. Furthermore, the

.\" .Sq \&Ft

.\" should be removed and

.\" .Sq \&Fo ,

.\" which ostensibly follows it, should follow the same convention as

.\" .Sq \&Va .

.\" .It

.\" .Sq \&Va

.\" should formalise that only one or two arguments are acceptable: a

.\" variable name and optional, preceding type.

.\" .It

.\" .Sq \&Fd

.\" is ambiguous. It's commonly used to indicate an include file in the

.\" synopsis section.

.\" .Sq \&In

.\" should be used, instead.

.\" .It

.\" Only the

.\" .Sq \-literal

.\" argument to

.\" .Sq \&Bd

.\" makes sense. The remaining ones should be removed.

.\" .It

.\" The

.\" .Sq \&Xo

.\" and

.\" .Sq \&Xc

.\" macros should be deprecated.

.\" .It

.\" The

.\" .Sq \&Dt

.\" macro lacks clarity. It should be absolutely clear which title will

.\" render when formatting the manual page.

.\" .It

.\" A

.\" .Sq \&Lx

.\" should be provided for Linux (\(`a la

.\" .Sq \&Ox ,

.\" .Sq \&Nx

.\" etc.).

.\" .It

.\" There's no way to refer to references in

.\" .Sq \&Rs/Re

.\" blocks.

.\" .It

.\" The \-split and \-nosplit dictates via

.\" .Sq \&An

.\" are re-set when entering and leaving the AUTHORS section.

.\" .El

.\" .

CVSweb