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

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

version 1.125, 2010/06/12 10:09:19

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

.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

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

.It Em DESCRIPTION

This expands upon the brief, one-line description in

.Em NAME .

Line 952 See also

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

Line 1677 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 1708 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 1722 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 1746 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 1769 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 1801 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 1879 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 2098 and

Line 2097 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 2114 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 2149 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 2169 Heirloom troff, the other significant troff implementa

.Pp

.Bl -dash -compact

.It

groff supports a

.Fl file Ar filename

argument to

.Sx \&Bd .

mandoc does not.

.It

groff behaves inconsistently when encountering

.Pf non- Sx \&Fa

children of

Line 2184 and

Line 2191 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 2249 and

Line 2256 and

.Fl right

are aliases for

.Fl left

in manodc. Furthermore, the

in mandoc. Furthermore, the

.Fl file Ar file

argument is ignored.

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

CVSweb