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

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

version 1.137, 2010/07/19 10:48:36

Line 52 manuals must have

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,

.Sq \&.\e" ,

.Sq \&.\e\*q ,

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

whitespace are stripped from input.

.Ss Reserved Characters

Line 135 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 1064 Closes a

Line 1043 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 1075 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 1088 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 1109 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 1157 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 1660 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 1697 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 1719 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 1770 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 1893 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 2033 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 2049 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 2063 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 2124 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 2149 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 2221 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 2185 line.

Line 2311 line.

.Ss \&Sc

.Ss \&Sh

.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

.Ss \&Sq

.Ss \&Ss

Line 2212 See also

Line 2350 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 2286 Heirloom troff, the other significant troff implementa

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

Line 2333 pseudo-macro as a line macro.

Line 2479 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 2369 Display offsets

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