mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.123, 2010/06/07 11:14:13

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

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 55 Text following a

Line 56 Text following a

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,

.Sq \&.\e" ,

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

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:

Line 167 also defined a set of package-specific

Line 168 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 478 they are separated by a vertical space, unless in the

Line 479 they are separated by a vertical space, unless in the

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 672 has multiple heads.

Line 686 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 973 See also

Line 998 See also

.Sx \&Aq .

.Ss \&Ap

Inserts an apostrophe without any surrounding white-space.

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 1039 Closes a

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 1063 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 1076 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 1094 As a scaling unit following the syntax described in

Line 1127 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 1118 See also

Line 1144 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 1589 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 .

.Ss \&Ek

Ends a keep context started by

.Sx \&Bk .

.Ss \&El

Ends a list context started by

.Sx \&Bl .

Line 1609 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 1620 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 1670 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 1791 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 1879 line itself.

Line 2019 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,

Line 1914 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 1927 Examples:

Line 2070 Examples:

See also

.Sx \&Mt .

.Ss \&Lp

Synonym for

.Sx \&Pp .

.Ss \&Ms

.Ss \&Mt

Format a

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

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

.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 1960 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 2010 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 2095 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 2169 Heirloom troff, the other significant troff implementa

Line 2438 Heirloom troff, the other significant troff implementa

.Pp

.Bl -dash -compact

.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

Line 2185 and

Line 2457 and

.Sx \&Fn

in the

.Em SYNOPSIS :

at times newline(s) are suppressed dependong on whether a prior

at times newline(s) are suppressed depending on whether a prior

.Sx \&Fn

has been invoked.

In mandoc, this is not the case.

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

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

CVSweb