mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.73, 2009/11/02 11:39:40

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

Line 131 and

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

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

Line 343 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 379 The

Line 419 The

macro(s) must precede the

.Sx \&Nd

macro.

.Pp

See

.Sx \&Nm

and

.Sx \&Nd .

.It Em LIBRARY

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

Line 389 this is as follows:

Line 434 this is as follows:

.Ed

.Pp

See

.Sx \&Lb

.Sx \&Lb .

for details.

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

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

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

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

.Sx \&Vt .

.It Em DESCRIPTION

This expands upon the brief, one-line description in

.Em NAME .

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

command), such as:

Line 440 The arguments are as follows:

Line 492 The arguments are as follows:

Print verbose information.

\&.El

.Ed

.Pp

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

.It Em IMPLEMENTATION NOTES

Line 495 for manuals in sections 1, 6, and 8; however, this pra

Line 548 for manuals in sections 1, 6, and 8; however, this pra

discouraged.

.Pp

See

.Sx \&Bl No \-diag .

.Sx \&Bl

.Fl diag .

.It Em ERRORS

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

Line 629 All macros have bodies; some

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

Line 716 or end of line.

Line 770 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 SYNOPSIS section line, else it is

.Sx In-line .

.Ss In-line

Line 809 then the macro accepts an arbitrary number of argument

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

Line 972 a function:

Line 1035 a function:

.Ed

.Ss \&Aq

Encloses its arguments in angled brackets.

.Pp

Examples:

.Bd -literal -offset indent

Line 1019 Note that these parameters do not begin with a hyphen.

Line 1082 Note that these parameters do not begin with a hyphen.

.Pp

Examples:

.Bd -literal -offset indent

\&.At

\&.At V.1

.Ed

.Pp

Line 1120 and

Line 1183 and

.Ss \&Bf

.Ss \&Bk

.Ss \&Bl

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

.\" specified by the

.\" .Sx \&It

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

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

.\" list types:

.\" .Bl -tag -width 12n

.\" .It Fl bullet

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

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

.\" .It Fl column

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

.\" the

.\" .Sx \&Bl

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

.\" .Fl column

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

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

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

.\" of columns.

.\" .It Fl dash

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

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

.\" .It Fl diag

.\" Like

.\" .Fl inset

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

.\" .It Fl enum

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

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

.\" enumeration.

.\" .It Fl hang

.\" Like

.\" .Fl tag ,

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

.\" they trail the head text.

.\" .It Fl hyphen

.\" Synonym for

.\" .Fl dash .

.\" .It Fl inset

.\" Like

.\" .Fl tag ,

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

.\" .It Fl item

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

.\" .It Fl ohang

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

.\" .It Fl tag

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

.\" after the head.

.\" .El

.\" .Pp

.\" More...

.\" .

.Ss \&Bo

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

arguments.

Line 1135 See also

Line 1251 See also

.Sx \&Bq .

.Ss \&Bq

Encloses its arguments in square brackets.

.Pp

Examples:

.Bd -literal -offset indent

Line 1282 manual. Its calling syntax is as follows:

Line 1398 manual. Its calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dd Cm date

.Pp

The

.Cm date

field may be either

.Ar $\&Mdocdate$ ,

Line 1331 See also

Line 1447 See also

.Sx \&Dq .

.Ss \&Dq

Encloses its arguments in double quotes.

.Pp

Examples:

.Bd -literal -offset indent

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

Line 1553 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 1556 is provided.

Line 1673 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 \-

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

is still printed.

.Pp

Examples:

.Bd -literal -offset indent

\&.Fl a b c

\&.Fl

\&.Op Fl o Ns Ar file

.Ed

.Pp