mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.120, 2010/06/06 10:49:56

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

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 333 must be the NAME section, consisting of at least one

Line 334 must be the NAME section, consisting of at least one

followed by

.Sx \&Nd .

.Pp

Following that, convention dictates specifying at least the SYNOPSIS and

Following that, convention dictates specifying at least the

DESCRIPTION sections, although this varies between manual sections.

.Em SYNOPSIS

and

.Em DESCRIPTION

sections, although this varies between manual sections.

.Pp

The following is a well-formed skeleton

.Nm

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

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

Manuals not in these sections generally don't need a

.Em SYNOPSIS .

.Pp

See

Some macros are displayed differently in the

.Sx \&Op ,

.Em SYNOPSIS

section, particularly

.Sx \&Nm ,

.Sx \&Cd ,

.Sx \&Fd ,

.Sx \&Fn ,

.Sx \&Ft ,

.Sx \&Fo ,

.Sx \&In ,

.Sx \&Vt ,

and

.Sx \&Vt .

.Sx \&Ft .

All of these macros are output on their own line. If two such

dissimilar macros are pair-wise invoked (except for

.Sx \&Ft

before

.Sx \&Fo

.Sx \&Fn ) ,

they are separated by a vertical space, unless in the case of

.Sx \&Fo ,

.Sx \&Fn ,

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 651 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 952 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 1073 As a scaling unit following the syntax described in

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

Line 1097 See also

Line 1140 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 keep block, containing a collection of macros or text

to be kept together in the output.

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:

.Bd -literal -offset indent

\&.Bk \-words

\&.Op o Ar output_file

\&.Ek

.Ed

.Pp

See also

.Sx \&Ek .

.Ss \&Bl

Begins a list composed of one or more list entries.

A list is associated with a type, which is a required argument.

Line 1570 and

Line 1668 and

.Ss \&Ec

.Ss \&Ed

.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 1656 This usage has been deprecated in favour of

Line 1758 This usage has been deprecated in favour of

Do not use this macro.

.Pp

See also

.Sx MANUAL STRUCTURE

and

.Sx \&In .

.Ss \&Fl

Command-line flag.

Line 1685 Its syntax is as follows:

Line 1789 Its syntax is as follows:

.Op Oo Cm argtype Oc Cm argname

.Ed

.Pp

If invoked in the

Function arguments are surrounded in parenthesis and

.Em SYNOPSIS

section, vertical space is asserted before and after the macro.

In all cases, the function arguments are surrounded in parenthesis and

are delimited by commas.

If no arguments are specified, blank parenthesis are output.

.Pp

Line 1702 Examples:

Line 1803 Examples:

.Ed

.Pp

See also

.Sx \&Fa ,

.Sx MANUAL STRUCTURE

.Sx \&Fo ,

.Sx \&Fc ,

and

.Sx \&Ft .

.Ss \&Fo

Line 1728 Invocations usually occur in the following context:

Line 1827 Invocations usually occur in the following context:

.Pf \. Sx \&Fc

.Ed

.Pp

In the

.Em SYNOPSIS

section, a

.Sx \&Fo

block is surrounded by vertical space unless

.Sx \&Ft

is the prior macro, in which case it is preceded by only a newline.

.Pp

.Sx \&Fo

scope is closed by

.Pp

See also

.Sx MANUAL STRUCTURE ,

.Sx \&Fa ,

.Sx \&Fc ,

and

.Sx \&Fn .

.Sx \&Fc .

.Ss \&Fr

.Ss \&Ft

A function type.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Ft Cm functype

.Pp

If invoked before a

.Sx \&Fo

.Sx \&Fn

in the

.Em SYNOPSIS

section, a line-break will follow.

Furthermore, if invoked in the

.Em SYNOPSIS

section, it will assert vertical space prior to its arguments.

.Pp

Examples:

.D1 \&.Ft int

.Bd -literal -offset indent -compact

Line 1772 Examples:

Line 1850 Examples:

.Ed

.Pp

See also

.Sx \&Fo ,

.Sx MANUAL STRUCTURE ,

.Sx \&Fc ,

.Sx \&Fn ,

and

.Sx \&Fn .

.Sx \&Fo .

.Ss \&Fx

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

if no argument is provided.

Line 1804 In the

Line 1882 In the

section (only if invoked as the line macro), the first argument is

preceded by

.Qq #include ,

the arguments is enclosed in angled braces, and a newline is asserted.

the arguments is enclosed in angled braces.

In all other invocations, only angled braces will enclose the argument.

.Pp

Examples

Examples:

.D1 \&.In sys/types

.Pp

See also

.Sx MANUAL STRUCTURE .

.Ss \&It

A list item.

The syntax of this macro depends on the list type.

Line 1880 line itself.

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

.Pp

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;

.Pp

will preserve the semicolon whitespace except for the last.

.Pp

Line 1941 Examples:

Line 2021 Examples:

.D1 \&.Mt discuss@manpages.bsd.lv

.Ss \&Nd

.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

.Ss \&Ns

.Ss \&Nx

Line 2098 and

Line 2214 and

.Ss \&Va

.Ss \&Vt

A variable type.

This is also used for indicating global variables in the SYNOPSIS

This is also used for indicating global variables in the

.Em SYNOPSIS

section, in which case a variable name is also specified.

Note that it accepts

.Sx Block partial-implicit

syntax when invoked as the first macro in the SYNOPSIS section, else it

syntax when invoked as the first macro in the

accepts ordinary

.Em SYNOPSIS

section, else it accepts ordinary

.Sx In-line

syntax.

.Pp

Line 2113 which is used for function return types.

Line 2231 which is used for function return types.

.Pp

Examples:

.D1 \&.Vt unsigned char

.D1 \&.Vt extern const char * const sys_signame[] ;

.D1 \&.Vt extern const char * const sys_signame[] \&;

.Pp

See also

.Sx \&Ft

.Sx MANUAL STRUCTURE

and

.Sx \&Va .

.Ss \&Xc

Line 2148 This behaviour is for compatibility with

Line 2266 This behaviour is for compatibility with

.Pp

Examples:

.D1 \&.Xr mandoc 1

.D1 \&.Xr mandoc 1 ;

.D1 \&.Xr mandoc 1 \&;

.D1 \&.Xr mandoc 1 \&Ns s behaviour

.Ss \&br

.Ss \&sp

Line 2168 Heirloom troff, the other significant troff implementa

Line 2286 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 2184 and

Line 2305 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 2242 In quoted literals, groff allowed pair-wise double-quo

Line 2363 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, the

in manodc. Furthermore, the

.Fl file Ar file

argument is ignored.

argument is not supported in mandoc.

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

.Fl ragged

and

CVSweb