mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.130 and 1.133

version 1.130, 2010/07/04 22:04:04

version 1.133, 2010/07/06 11:07:21

Line 1064 Closes a

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 1088 Centre-justify each line.

Line 1096 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 1101 the width of standard indentation;

Line 1109 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 1122 As the calculated string length of the opaque string.

Line 1130 As the calculated string length of the opaque string.

If not provided an argument, it will be ignored.

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

Line 1178 See also

and

.Sx \&Sy .

.Ss \&Bk

Begins a keep block, containing a collection of macros or text

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

to be kept together in the output.

Its syntax is as follows:

One argument is required; additional arguments are ignored.

Currently, the only argument implemented is

.Fl words ,

requesting to keep together all words of the contained text

on the same output line.

.Fl lines

argument to keep together all lines of the contained text

on the same page has been desired for a long time,

but has never been implemented.

.Pp

Examples:

.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 o Ar output_file

\&.Op Fl f Ar flags

\&.Op Fl o Ar output

\&.Ek

.Ed

.Pp

See also

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

.Sx \&Ek .

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

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

Line 1690 Examples:

Line 1718 Examples:

.D1 \&.Em Warnings!

.D1 \&.Em Remarks :

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

Line 1740 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 1751 Examples:

Line 1791 Examples:

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

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

Line 1995 Examples:

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

.Ss \&Lk

Format a hyperlink.

Its syntax is as follows:

Line 2008 Examples:

Line 2070 Examples:

See also

.Sx \&Mt .

.Ss \&Lp

Synonym for

.Sx \&Pp .

.Ss \&Ms

.Ss \&Mt

Format a

Line 2020 Its syntax is as follows:

Line 2084 Its syntax is as follows:

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

Line 2058 macro rather than

Line 2145 macro rather than

.Sx \&Nm

to mark up the name of the manual page.

.Ss \&No

.Qq noop

macro used to terminate prior macro contexts.

.Pp

Examples:

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

.Ss \&Ns

.Ss \&Nx

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

Line 2077 See also

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

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

Line 2127 See also

Line 2242 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 Qq 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

.Ss \&Ql

.Ss \&Qo

Line 2212 See also

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

Line 2369 Display offsets

Line 2521 Display offsets

and

.Fl offset Ar right

are disregarded in mandoc.

Furthermore, the

Furthermore, troff specifies a

.Fl file Ar file

argument is not supported in mandoc.

argument that is not supported in mandoc.

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

.Fl ragged

and

CVSweb