mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.77 and 1.85

version 1.77, 2009/11/12 05:50:12

version 1.85, 2010/03/21 18:16:41

Line 132 and

Terms may be text-decorated using the

.Sq \ef

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

(revert to previous mode):

.Pp

.D1 \efBbold\efR \efIitalic\efP

.Pp

Line 140 A numerical representation 3, 2, or 1 (bold, italic, a

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

Line 170 for arbitrary-digit numerals:

.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 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 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 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 429 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 465 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 480 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 535 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 669 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 756 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 849 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 1012 a function:

Line 1035 a function:

.Ed

.Ss \&Aq

Encloses its arguments in angled brackets.

.Pp

Examples:

.Bd -literal -offset indent

Line 1059 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 1160 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 1175 See also

Line 1251 See also

.Sx \&Bq .

.Ss \&Bq

Encloses its arguments in square brackets.

.Pp

Examples:

.Bd -literal -offset indent

Line 1322 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 1371 See also

Line 1447 See also

.Sx \&Dq .

.Ss \&Dq

Encloses its arguments in double quotes.

.Pp

Examples:

.Bd -literal -offset indent

Line 1477 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 longsoon ,

.Ar luna88k ,

.Ar mac68k ,

.Ar macppc ,

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