mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.43 and 1.45

version 1.43, 2009/07/14 15:57:08

version 1.45, 2009/07/17 12:40:48

Line 177 followed by

.Pp

Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,

but non-compulsory.

.\" SUB-SECTION----------------------

.\" .Ss Classification

.\" Macros are classified by their scope rules: block full-explicit (BFE),

.\" block partial-explicit (BPE), block full-implicit (BFI), block

.\" partial-implicit (BPI), and in-line.

.\" SUB-SECTION----------------------

.\" .Ss Scope

.\" .Bl -inset

.\" .\" LIST-ITEM

.\" .It Em Block

.\" macros enclose other block macros, in-line macros or text, and

.\" may span multiple lines.

.\" .Bl -inset -offset indent

.\" .\" LIST-ITEM

.\" .It Em Full-block

.\" macros always span multiple lines. They consist of zero or

.\" more

.\" .Qq heads ,

.\" subsequent macros or text on the same line following invocation; an

.\" optional

.\" .Qq body ,

.\" which spans subsequent lines of text or macros; and an optional

.\" .Qq tail ,

.\" macros or text on the same line following closure.

.\" .\" LIST-ITEM

.\" .It Em Partial-block

.\" macros may span multiple lines. They consists of a optional

.\" .Qq head ,

.\" text immediately following invocation; always a

.\" .Qq body ,

.\" text or macros following the head on the same and subsequent lines; and

.\" optionally a

.\" .Qq tail ,

.\" text immediately following closure.

.\" .\" LIST-ITEM

.\" .It Em In-line

.\" macros may only enclose text and span at most a single line.

.\" .El

.\" SUB-SECTION----------------------

.\" .Ss Closure

.\" Closure of a macro's scope depends first on its classification, then

.\" on whether it's parsable. In this table,

.\" .Sq BFE

.\" refers to block full-explicit and so on.

.\" .\" PARAGRAPH------------

.\" .Pp

.\" .Bl -tag -width 12n -offset indent -compact

.\" .It BPE , BFE

.\" corresponding explicit closure macro

.\" .It BFI

.\" end-of-file or a corresponding implicit closure macro

.\" .It BPI

.\" end-of-line (body may be closed by >0 space-separated

.\" .Sx Reserved Characters ,

.\" although block scope will still be open)

.\" .It INL

.\" end-of-line

.\" .El

.\" PARAGRAPH------------

.\" .Pp

.\" If a macro (block or in-line) is parsable, it may also be closed out by

.\" one of the following scenarios (unless specifically noted otherwise):

.\" .\" PARAGRAPH------------

.\" .Pp

.\" .Bl -dash -offset indent -compact

.\" .It

.\" a sequence of >0 space-separated

.\" .Sx Reserved Characters ,

.\" .It

.\" another macro,

.\" .It

.\" end-of-line, or

.\" .It

.\" completion of a set number of arguments.

.\" .El

.\" PARAGRAPH------------

.\" .Pp

.\" If >0 space-separated

.\" .Sx Reserved Characters

.\" are followed by non-reserved characters, the behaviour differs per

.\" macro. In general, scope of the macro is closed and re-opened:

.\" subsequent tokens are interpreted as if the scope had just been opened.

.\" In other circumstances, scope is simply closed out.

.\" SECTION---------------------------------------------

.Sh MACRO SYNTAX

Every line beginning with the control character

Line 304 contains a head.

Line 220 contains a head.

.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

.It \&Bd Ta \&No Ta \&No Ta closed by \&Ed

.It \&Ed Ta \&No Ta \&No Ta opened by \&Bd

.It \&Bl Ta \&No Ta \&No Ta closed by \&El

.It \&El Ta \&No Ta \&No Ta opened by \&Bl

.It \&Bf Ta \&No Ta \&No Ta closed by \&Ef

.It \&Ef Ta \&No Ta \&No Ta opened by \&Bf

.It \&Bk Ta \&No Ta \&No Ta closed by \&Ek

.It \&Bl Ta \&No Ta \&No Ta closed by \&El

.It \&Ed Ta \&No Ta \&No Ta opened by \&Bd

.It \&Ef Ta \&No Ta \&No Ta opened by \&Bf

.It \&Ek Ta \&No Ta \&No Ta opened by \&Bk

.It \&El Ta \&No Ta \&No Ta opened by \&Bl

.El

.\" SUB-SECTION----------------------

.Ss Block full-implicit

Line 334 may have multiple heads.

Line 250 may have multiple heads.

.Pp

.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

.It \&It Ta \&No Ta Yes Ta closed by \&It, \&El

.It \&Nd Ta \&No Ta \&No Ta closed by \&Sh

.It \&Sh Ta \&No Ta \&No Ta closed by \&Sh

.It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss

.It \&It Ta \&No Ta Yes Ta closed by \&It, \&El

.El

.\" SUB-SECTION----------------------

.Ss Block partial-explicit

Line 358 and/or tail

Line 274 and/or tail

.Pp

.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope

.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac

.It \&Ac Ta Yes Ta Yes Ta opened by \&Ao

.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac

.It \&Bc Ta Yes Ta Yes Ta closed by \&Bo

.It \&Bo Ta Yes Ta Yes Ta opened by \&Bc

.It \&Pc Ta Yes Ta Yes Ta closed by \&Po

.It \&Po Ta Yes Ta Yes Ta opened by \&Pc

.It \&Do Ta Yes Ta Yes Ta closed by \&Dc

.It \&Dc Ta Yes Ta Yes Ta opened by \&Do

.It \&Xo Ta Yes Ta Yes Ta closed by \&Xc

.It \&Xc Ta Yes Ta Yes Ta opened by \&Xo

.It \&Bro Ta Yes Ta Yes Ta closed by \&Brc

.It \&Brc Ta Yes Ta Yes Ta opened by \&Bro

.It \&Oc Ta Yes Ta Yes Ta closed by \&Oo

.It \&Bro Ta Yes Ta Yes Ta closed by \&Brc

.It \&Oo Ta Yes Ta Yes Ta opened by \&Oc

.It \&Dc Ta Yes Ta Yes Ta opened by \&Do

.It \&So Ta Yes Ta Yes Ta closed by \&Sc

.It \&Do Ta Yes Ta Yes Ta closed by \&Dc

.It \&Sc Ta Yes Ta Yes Ta opened by \&So

.It \&Fc Ta Yes Ta Yes Ta opened by \&Fo

.It \&Fo Ta \&No Ta \&No Ta closed by \&Fc

.It \&Ec Ta Yes Ta Yes Ta opened by \&Eo

.It \&Eo Ta Yes Ta Yes Ta closed by \&Ec

.It \&Fc Ta Yes Ta Yes Ta opened by \&Fo

.It \&Fo Ta \&No Ta \&No Ta closed by \&Fc

.It \&Oc Ta Yes Ta Yes Ta closed by \&Oo

.It \&Oo Ta Yes Ta Yes Ta opened by \&Oc

.It \&Pc Ta Yes Ta Yes Ta closed by \&Po

.It \&Po Ta Yes Ta Yes Ta opened by \&Pc

.It \&Qc Ta Yes Ta Yes Ta opened by \&Oo

.It \&Qo Ta Yes Ta Yes Ta closed by \&Oc

.It \&Re Ta \&No Ta \&No Ta opened by \&Rs

.It \&Rs Ta \&No Ta \&No Ta closed by \&Re

.It \&Sc Ta Yes Ta Yes Ta opened by \&So

.It \&So Ta Yes Ta Yes Ta closed by \&Sc

.It \&Xc Ta Yes Ta Yes Ta opened by \&Xo

.It \&Xo Ta Yes Ta Yes Ta closed by \&Xc

.El

.\" SUB-SECTION----------------------

.Ss Block partial-implicit

Line 396 or end of line.

Line 312 or end of line.

.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable

.It \&Aq Ta Yes Ta Yes

.It \&Op Ta Yes Ta Yes

.It \&Bq Ta Yes Ta Yes

.It \&Dq Ta Yes Ta Yes

.It \&Pq Ta Yes Ta Yes

.It \&Qq Ta Yes Ta Yes

.It \&Sq Ta Yes Ta Yes

.It \&Brq Ta Yes Ta Yes

.It \&D1 Ta \&No Ta \&Yes

.It \&Dl Ta \&No Ta Yes

.It \&Dq Ta Yes Ta Yes

.It \&Op Ta Yes Ta Yes

.It \&Pq Ta Yes Ta Yes

.It \&Ql Ta Yes Ta Yes

.It \&Qq Ta Yes Ta Yes

.It \&Sq Ta Yes Ta Yes

.El

.\" SUB-SECTION----------------------

.Ss In-line

Line 427 then the macro accepts an arbitrary number of argument

Line 343 then the macro accepts an arbitrary number of argument

.Pp

.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent

.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments

.It \&Dd Ta \&No Ta \&No Ta >0

.It \&Dt Ta \&No Ta \&No Ta n

.It \&Os Ta \&No Ta \&No Ta n

.It \&Pp Ta \&No Ta \&No Ta 0

.It \&Ad Ta Yes Ta Yes Ta n

.It \&An Ta Yes Ta Yes Ta n

.It \&Ar Ta Yes Ta Yes Ta n

.It \&Cd Ta Yes Ta \&No Ta >0

.It \&Cm Ta Yes Ta Yes Ta n

.It \&Dv Ta Yes Ta Yes Ta n

.It \&Er Ta Yes Ta Yes Ta >0

.It \&Ev Ta Yes Ta Yes Ta n

.It \&Ex Ta \&No Ta \&No Ta 0

.It \&Fa Ta Yes Ta Yes Ta n

.It \&Fd Ta \&No Ta \&No Ta >0

.It \&Fl Ta Yes Ta Yes Ta n

.It \&Fn Ta Yes Ta Yes Ta >0

.It \&Ft Ta Yes Ta Yes Ta n

.It \&Ic Ta Yes Ta Yes Ta >0

.It \&In Ta \&No Ta \&No Ta n

.It \&Li Ta Yes Ta Yes Ta n

.It \&Nm Ta Yes Ta Yes Ta n

.It \&Ot Ta \&No Ta \&No Ta n

.It \&Pa Ta Yes Ta Yes Ta n

.It \&Rv Ta \&No Ta \&No Ta 0

.It \&St Ta \&No Ta Yes Ta 1

.It \&Va Ta Yes Ta Yes Ta n

.It \&Vt Ta Yes Ta Yes Ta >0

.It \&Xr Ta Yes Ta Yes Ta >0, <3

.It \&%A Ta \&No Ta \&No Ta >0

.It \&%B Ta \&No Ta \&No Ta >0

.It \&%C Ta \&No Ta \&No Ta >0

Line 468 then the macro accepts an arbitrary number of argument

Line 355 then the macro accepts an arbitrary number of argument

.It \&%R Ta \&No Ta \&No Ta >0

.It \&%T Ta \&No Ta \&No Ta >0

.It \&%V Ta \&No Ta \&No Ta >0

.It \&Ad Ta Yes Ta Yes Ta n

.It \&An Ta Yes Ta Yes Ta n

.It \&Ap Ta Yes Ta Yes Ta 0

.It \&Ar Ta Yes Ta Yes Ta n

.It \&At Ta Yes Ta Yes Ta 1

.It \&Bsx Ta Yes Ta Yes Ta n

.It \&Bt Ta \&No Ta \&No Ta 0

.It \&Bx Ta Yes Ta Yes Ta n

.It \&Cd Ta Yes Ta \&No Ta >0

.It \&Cm Ta Yes Ta Yes Ta n

.It \&Db Ta \&No Ta \&No Ta 1

.It \&Dd Ta \&No Ta \&No Ta >0

.It \&Dt Ta \&No Ta \&No Ta n

.It \&Dv Ta Yes Ta Yes Ta n

.It \&Dx Ta Yes Ta Yes Ta n

.It \&Em Ta Yes Ta Yes Ta >0

.It \&En Ta \&No Ta \&No Ta 0

.It \&Er Ta Yes Ta Yes Ta >0

.It \&Es Ta \&No Ta \&No Ta 0

.It \&Ev Ta Yes Ta Yes Ta n

.It \&Ex Ta \&No Ta \&No Ta 0

.It \&Fa Ta Yes Ta Yes Ta n

.It \&Fd Ta \&No Ta \&No Ta >0

.It \&Fl Ta Yes Ta Yes Ta n

.It \&Fn Ta Yes Ta Yes Ta >0

.It \&Fr Ta \&No Ta \&No Ta n

.It \&Ft Ta Yes Ta Yes Ta n

.It \&Fx Ta Yes Ta Yes Ta n

.It \&Hf Ta \&No Ta \&No Ta n

.It \&Ic Ta Yes Ta Yes Ta >0

.It \&In Ta \&No Ta \&No Ta n

.It \&Lb Ta \&No Ta \&No Ta 1

.It \&Li Ta Yes Ta Yes Ta n

.It \&Lk Ta Yes Ta Yes Ta n

.It \&Lp Ta \&No Ta \&No Ta 0

.It \&Ms Ta Yes Ta Yes Ta >0

.It \&Mt Ta Yes Ta Yes Ta >0

.It \&Nm Ta Yes Ta Yes Ta n

.It \&No Ta Yes Ta Yes Ta 0

.It \&Ns Ta Yes Ta Yes Ta 0

.It \&Nx Ta Yes Ta Yes Ta n

.It \&Os Ta \&No Ta \&No Ta n

.It \&Ot Ta \&No Ta \&No Ta n

.It \&Ox Ta Yes Ta Yes Ta n

.It \&Pa Ta Yes Ta Yes Ta n

.It \&Pf Ta \&No Ta Yes Ta 1

.It \&Pp Ta \&No Ta \&No Ta 0

.It \&Rv Ta \&No Ta \&No Ta 0

.It \&Sm Ta \&No Ta \&No Ta 1

.It \&St Ta \&No Ta Yes Ta 1

.It \&Sx Ta Yes Ta Yes Ta >0

.It \&Sy Ta Yes Ta Yes Ta >0

.It \&Tn Ta Yes Ta Yes Ta >0

.It \&Ux Ta Yes Ta Yes Ta n

.It \&Dx Ta Yes Ta Yes Ta n

.It \&Bt Ta \&No Ta \&No Ta 0

.It \&Hf Ta \&No Ta \&No Ta n

.It \&Fr Ta \&No Ta \&No Ta n

.It \&Ud Ta \&No Ta \&No Ta 0

.It \&Lb Ta \&No Ta \&No Ta 1

.It \&Ux Ta Yes Ta Yes Ta n

.It \&Ap Ta Yes Ta Yes Ta 0

.It \&Va Ta Yes Ta Yes Ta n

.It \&Lp Ta \&No Ta \&No Ta 0

.It \&Vt Ta Yes Ta Yes Ta >0

.It \&Lk Ta Yes Ta Yes Ta n

.It \&Xr Ta Yes Ta Yes Ta >0, <3

.It \&Mt Ta Yes Ta Yes Ta >0

.It \&br Ta \&No Ta \&No Ta 0

.It \&Es Ta \&No Ta \&No Ta 0

.It \&sp Ta \&No Ta \&No Ta 1

.It \&En Ta \&No Ta \&No Ta 0

.El

.\" SECTION---------------------------------------------

.Sh COMPATIBILITY

Line 514 file re-write

Line 432 file re-write

.Bl -dash -compact

.\" LIST-ITEM

.It

The

.Sq \&sp

macro does not accept negative numbers.

.\" LIST-ITEM

.It

Some character sequences in groff are not handled depending on escape

style, e.g.,

.Sq \e(ba

Line 540 made historic groff

Line 463 made historic groff

but is a proper delimiter in this implementation.

.\" LIST-ITEM

.It

.Sq \&.It \-nested

.Sq \&It \-nested

is assumed for all lists (it wasn't in historic groff): any list may be

nested and

.Sq \-enum

lists will restart the sequence only for the sub-list.

.\" LIST-ITEM

.It

.Sq \&.It \-column

.Sq \&It \-column

syntax where column widths may be preceded by other arguments (instead

of proceeded) is not supported.

.\" LIST-ITEM

.It

The

.Sq \&.At

.Sq \&At

macro only accepts a single parameter.

.\" LIST-ITEM

.It

Some manuals use

.Sq \&.Li

.Sq \&Li

incorrectly by following it with a reserved character and expecting the

delimiter to render. This is not supported.

.\" LIST-ITEM

Line 570 versions of groff seem to dither on this.

Line 493 versions of groff seem to dither on this.

.\" LIST-ITEM

.It

In groff, the

.Sq \&.Fo

.Sq \&Fo

macro only produces the first parameter. This is no longer the case.

.El

.\" SECTION---------------------------------------------

Line 591 There are many ambiguous parts of mdoc.

Line 514 There are many ambiguous parts of mdoc.

.Bl -dash -compact

.\" LIST-ITEM

.It

.Sq \&.Fa

.Sq \&Fa

should be

.Sq \&.Va

.Sq \&Va

as function arguments are variables.

.\" LIST-ITEM

.It

.Sq \&.Ft

.Sq \&Ft

should be

.Sq \&.Vt

.Sq \&Vt

as function return types are still types. Furthermore, the

.Sq \&.Ft

.Sq \&Ft

should be removed and

.Sq \&.Fo ,

.Sq \&Fo ,

which ostensibly follows it, should follow the same convention as

.Sq \&.Va .

.Sq \&Va .

.\" LIST-ITEM

.It

.Sq \&.Va

.Sq \&Va

should formalise that only one or two arguments are acceptable: a

variable name and optional, preceding type.

.\" LIST-ITEM

.It

.Sq \&.Fd

.Sq \&Fd

is ambiguous. It's commonly used to indicate an include file in the

synopsis section.

.Sq \&.In

.Sq \&In

should be used, instead.

.\" LIST-ITEM

.It

Only the

.Sq \-literal

argument to

.Sq \&.Bd

.Sq \&Bd

makes sense. The remaining ones should be removed.

.\" LIST-ITEM

.It

The

.Sq \&.Xo

.Sq \&Xo

and

.Sq \&.Xc

.Sq \&Xc

macros should be deprecated.

.\" LIST-ITEM

.It

The

.Sq \&.Dt

.Sq \&Dt

macro lacks clarity. It should be absolutely clear which title will

render when formatting the manual page.

.\" LIST-ITEM

.It

.Sq \&.Lx

.Sq \&Lx

should be provided for Linux (\(`a la

.Sq \&.Ox ,

.Sq \&Ox ,

.Sq \&.Nx

.Sq \&Nx

etc.).

.\" LIST-ITEM

.It

There's no way to refer to references in

.Sq \&.Rs/.Re

.Sq \&Rs/Re

blocks.

.\" LIST-ITEM

.It

The \-split and \-nosplit arguments to

.Sq \&.An

.Sq \&An

are inane.

.El

CVSweb