mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.114 and 1.121

version 1.114, 2010/06/03 14:29:52

version 1.121, 2010/06/06 22:25:56

Line 33 section describes compatibility with other troff \-mdo

.Pp

.Nm

document follows simple rules: lines beginning with the control

character

.Sq \.

are parsed for macros. Other lines are interpreted within the scope of

Line 122 escape followed by an indicator: B (bold), I, (italic)

A numerical representation 3, 2, or 1 (bold, italic, and Roman,

respectively) may be used instead.

A text decoration is valid within

the current font scope only: if a macro opens a font scope alongside

its own scope, such as

.Sx \&Bf

.Cm \&Sy ,

Line 1332 See also

and

.Sx \&Dl .

.Ss \&Db

Start a debugging context.

This macro is parsed, but generally ignored.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Db Cm on | off

.Ss \&Dc

Closes a

.Sx \&Do

Line 1341 Document date.

Line 1346 Document date.

This is the mandatory first macro of any

.Nm

manual.

Its calling syntax is as follows:

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dd Cm date

.D1 Pf \. Sx \&Dd Cm date

.Pp

The

.Cm date

Line 1402 Document title.

Line 1407 Document title.

This is the mandatory second macro of any

.Nm

file.

Its calling syntax is as follows:

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Dt

.Oo

.Cm title

.Oo

.Cm section

.Op Cm volume | arch

.Oc

.Ed

.Pp

.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch

.Pp

Its arguments are as follows:

.Bl -tag -width Ds -offset Ds

.It Cm title

Line 1559 and

Line 1572 and

.Ss \&Ef

.Ss \&Ek

.Ss \&El

Ends a list context started by

.Sx \&Bl .

.Pp

See also

.Sx \&Bl

and

.Sx \&It .

.Ss \&Em

Denotes text that should be emphasised.

Note that this is a presentation term and should not be used for

Line 1598 is not provided, the document's name as stipulated in

Line 1618 is not provided, the document's name as stipulated in

.Sx \&Nm

is provided.

.Ss \&Fa

Function argument.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Sx \&Fa

.Op Cm argtype

.Cm argname

.Ed

.Pp

This may be invoked for names with or without the corresponding type.

It is also used to specify the field name of a structure.

Most often, the

.Sx \&Fa

macro is used in the

.Em SYNOPSIS

within

.Sx \&Fo

section when documenting multi-line function prototypes.

If invoked with multiple arguments, the arguments are separated by a

comma.

Furthermore, if the following macro is another

.Sx \&Fa ,

the last argument will also have a trailing comma.

.Pp

Examples:

.D1 \&.Fa \(dqconst char *p\(dq

.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq

.D1 \&.Fa foo

.Pp

See also

.Sx \&Fo .

.Ss \&Fc

.Ss \&Fd

Historically used to document include files.

This usage has been deprecated in favour of

.Sx \&In .

Do not use this macro.

.Pp

See also

.Sx \&In .

.Ss \&Fl

Command-line flag.

Used when listing arguments to command-line utilities.

Line 1619 Examples:

Line 1676 Examples:

See also

.Sx \&Cm .

.Ss \&Fn

A function name.

Its syntax is as follows:

.Bd -ragged -offset indent

.Pf \. Ns Sx \&Fn

.Op Cm functype

.Cm funcname

.Op Oo Cm argtype Oc Cm argname

.Ed

.Pp

If invoked in the

.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

Examples:

.D1 \&.Fn "int funcname" "int arg0" "int arg1"

.D1 \&.Fn funcname "int arg0"

.D1 \&.Fn funcname arg0

.Bd -literal -offset indent -compact

\&.Ft functype

\&.Fn funcname

.Ed

.Pp

See also

.Sx \&Fa ,

.Sx \&Fo ,

.Sx \&Fc ,

and

.Sx \&Ft .

.Ss \&Fo

Begin a function block.

This is a multi-line version of

.Sx \&Fn .

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Fo Cm funcname

.Pp

Invocations usually occur in the following context:

.Bd -ragged -offset indent

.Pf \. Sx \&Ft Cm functype

.br

.Pf \. Sx \&Fo Cm funcname

.br

.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname

.br

\.\.\.

.br

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

\&.Ft functype

\&.Fn funcname

.Ed

.Pp

See also

.Sx \&Fo ,

.Sx \&Fc ,

and

.Sx \&Fn .

.Ss \&Fx

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

if no argument is provided.

Line 1642 and

Line 1796 and

.Ss \&Hf

.Ss \&Ic

.Ss \&In

.Qq include

file.

In the

.Em SYNOPSIS

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.

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

.Pp

Examples

.D1 \&.In sys/types

.Ss \&It

A list item. The syntax of this macro depends on the list type.

A list item.

The syntax of this macro depends on the list type.

.Pp

Lists

of type

Line 1652 of type

Line 1820 of type

.Fl inset ,

and

.Fl diag

have the following calling syntax:

have the following syntax:

.Pp

.D1 \. Ns Sx \&It Cm args

.D1 Pf \. Sx \&It Cm args

.Pp

Lists of type

.Fl bullet ,

Line 1663 Lists of type

Line 1831 Lists of type

.Fl hyphen

and

.Fl item

have the following calling syntax:

have the following syntax:

.Pp

.D1 \. Ns Sx \&It

.D1 Pf \. Sx \&It

.Pp

with subsequent lines interpreted within the scope of the

.Sx \&It

Line 1676 or another

Line 1844 or another

.Pp

The

.Fl tag

list has syntax

list has the following syntax:

.Pp

.D1 \. Ns Sx \&It Op Cm args

.D1 Pf \. Sx \&It Op Cm args

.Pp

with subsequent lines interpreted as with

Subsequent lines are interpreted as with

.Fl bullet

and family.

The line arguments correspond to the list's left-hand side; body

Line 1689 arguments correspond to the list's contents.

Line 1857 arguments correspond to the list's contents.

The

.Fl column

list is the most complicated.

Its syntax is

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&It Op Cm args

.D1 Pf \. Sx \&It Op Cm args

.Pp

where

The

.Cm args

are phrases, a mix of macros and text corresponding to a line column,

delimited by tabs or the special

Line 1717 phrases on an

Line 1885 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 1725 See also

Line 1893 See also

.Sx \&Bl .

.Ss \&Lb

Specify a library.

The calling syntax is as follows:

The syntax is as follows:

.Pp

.D1 \. Ns Sx \&Lb Cm library

.D1 Pf \. Sx \&Lb Cm library

.Pp

The

.Cm library

Line 1749 Examples:

Line 1917 Examples:

.Ss \&Li

.Ss \&Lk

Format a hyperlink.

The calling syntax is as follows:

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Lk Cm uri Op Cm name

.D1 Pf \. Sx \&Lk Cm uri Op Cm name

.Pp

Examples:

.D1 \&.Lk http://bsd.lv "The BSD.lv Project"

Line 1762 See also

Line 1930 See also

.Ss \&Lp

.Ss \&Ms

.Ss \&Mt

Format a

.Qq mailto:

hyperlink.

Its syntax is as follows:

.Pp

.D1 Pf \. Sx \&Mt Cm address

.Pp

Examples:

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

.Ss \&Nd

.Ss \&Nm

.Ss \&No

Line 1791 Document operating system version.

Line 1968 Document operating system version.

This is the mandatory third macro of

any

.Nm

file. Its calling syntax is as follows:

file.

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Os Op Cm system

.D1 Pf \. Sx \&Os Op Cm system

.Pp

The optional

.Cm system

Line 1865 The block macro may only contain

Line 2043 The block macro may only contain

.Sx \&%Q ,

.Sx \&%R ,

.Sx \&%T ,

.Sx \&%U ,

and

.Sx \&%V

child macros (at least one must be specified).

Line 1934 which is used for function return types.

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

Line 1950 since this limit has been lifted, the macro has been d

Line 2129 since this limit has been lifted, the macro has been d

.Ss \&Xr

Link to another manual

.Pq Qq cross-reference .

Its calling syntax is

Its syntax is as follows:

.Pp

.D1 \. Ns Sx \&Xr Cm name section

.D1 Pf \. Sx \&Xr Cm name section

.Pp

The

.Cm name

Line 1969 This behaviour is for compatibility with

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

Line 2168 Heirloom troff, the other significant troff implementa

.Pp

.Bl -dash -compact

.It

groff behaves inconsistently when encountering

.Pf non- Sx \&Fa

children of

.Sx \&Fo

regarding spacing between arguments.

In mandoc, this is not the case: each argument is consistently followed

by a single space and the trailing

.Sq \&)

suppresses prior spacing.

.It

groff behaves inconsistently when encountering

.Sx \&Ft

and

.Sx \&Fn

in the

.Em SYNOPSIS :

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

.Sx \&Fn

has been invoked.

In mandoc, this is not the case.

See

.Sx \&Ft

and

.Sx \&Fn

for the normalised behaviour.

.It

Historic groff does not break before an

.Sx \&Fn

when not invoked as the line macro in the

.Em SYNOPSIS

section.

.It

Historic groff formats the

.Sx \&In

badly: trailing arguments are trashed and

.Em SYNOPSIS

is not specially treated.

.It

groff does not accept the

.Sq \&Ta

pseudo-macro as a line macro.

mandoc does.

.It

The comment syntax

.Sq \e."

is no longer accepted.

Line 2059 Some manuals use

Line 2281 Some manuals use

incorrectly by following it with a reserved character and expecting the

delimiter to render.

This is not supported in mandoc.

.It

In groff, the

.Sx \&Fo

macro only produces the first parameter.

This is not the case in mandoc.

.It

In groff, the

.Sx \&Cd ,

CVSweb