mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.55 and 1.60

version 1.55, 2009/07/29 08:58:11

version 1.60, 2009/09/28 22:09:08

Line 17

.Dd $Mdocdate$

.Dt MDOC 7

.Os

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

.Sh NAME

.Nm mdoc

.Nd mdoc language reference

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

.Sh DESCRIPTION

The

.Nm mdoc

Line 35 The

Line 37 The

.Sx COMPATIBILITY

section describes compatibility with

.Xr groff 1 .

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

.Pp

.Nm

Line 48 prior macros:

Line 50 prior macros:

\&.Sh Macro lines change control state.

Other lines are interpreted within the current state.

.Ed

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

.Sh LANGUAGE SYNTAX

.Nm

documents may contain only graphable 7-bit ASCII characters, the space

Line 56 character, and, in certain circumstances, the tab char

Line 59 character, and, in certain circumstances, the tab char

manuals must have

.Ux

line terminators.

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

.Ss Comments

Text following a

.Sq \e" ,

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.

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

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

whitespace are stripped from input.

.Ss Reserved Characters

Within a macro line, the following characters are reserved:

.Bl -tag -width Ds -offset indent -compact

Line 91 Within a macro line, the following characters are rese

Line 97 Within a macro line, the following characters are rese

.It \&|

.Pq vertical bar

.El

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

.Pp

Use of reserved characters is described in

.Sx MACRO SYNTAX .

Line 99 For general use in macro lines, these characters must

Line 105 For general use in macro lines, these characters must

with a non-breaking space

.Pq Sq \e&

or, if applicable, an appropriate escape sequence used.

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

.Ss Special Characters

Special characters may occur in both macro and free-form lines.

Sequences begin with the escape character

Line 118 for a complete list. Examples include

Line 125 for a complete list. Examples include

and

.Sq \ee

.Pq back-slash .

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

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

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

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

(Roman, or reset). This form is not recommended for

.Nm ,

which encourages semantic, not presentation, annotation.

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

.Ss Predefined Strings

Historically,

.Xr groff 1

Line 151 for a complete list. Examples include

Line 160 for a complete list. Examples include

and

.Sq \e*(Ba

.Pq vertical bar .

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

.Ss Whitespace

In non-literal free-form lines, consecutive blocks of whitespace are

pruned from input and added later in the output filter, if applicable:

Line 161 These spaces are pruned from input.

Line 171 These spaces are pruned from input.

These are not.

\&.Ed

.Ed

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

.Pp

In macro lines, whitespace delimits arguments and is discarded. If

arguments are quoted, whitespace within the quotes is retained.

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

.Pp

Blank lines are only permitted within literal contexts, as are lines

containing only whitespace. Tab characters are only acceptable when

delimiting

.Sq \&Bl \-column

or when in a literal context.

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

.Ss Quotation

Macro arguments may be quoted with a double-quote to group

space-delimited terms or to retain blocks of whitespace. A quoted

argument begins with a double-quote preceded by whitespace. The next

double-quote not pair-wise adjacent to another double-quote terminates

the literal, regardless of surrounding whitespace.

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

.Pp

This produces tokens

.Sq a" ,

Line 193 considered literal text. Thus, the following produces

Line 204 considered literal text. Thus, the following produces

.Bd -literal -offset indent

\&.Em "Em a"

.Ed

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

.Pp

In free-form mode, quotes are regarded as opaque text.

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

.Sh MANUAL STRUCTURE

Each

.Nm

Line 213 followed by

Line 225 followed by

\&.Dd $\&Mdocdate$

\&.Dt mdoc 7

\&.Os

\&.

\&.Sh NAME

\&.Nm mdoc

\&.Nm foo

\&.Nd mdoc language reference

\&.Nd a description goes here

\&.\e\*q The next is for sections 2 & 3 only.

\&.\e\*q .Sh LIBRARY

\&.

\&.Sh SYNOPSIS

\&.Nm foo

\&.Op Fl options

\&.Ar

\&.

\&.Sh DESCRIPTION

The

\&.Nm

utility processes files ...

\&.\e\*q .Sh IMPLEMENTATION NOTES

\&.\e\*q The next is for sections 1 & 8 only.

\&.\e\*q .Sh EXIT STATUS

\&.\e\*q The next is for sections 2, 3, & 9 only.

\&.\e\*q .Sh RETURN VALUES

\&.\e\*q The next is for sections 1, 6, 7, & 8 only.

\&.\e\*q .Sh ENVIRONMENT

\&.\e\*q .Sh FILES

\&.\e\*q .Sh EXAMPLES

\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

\&.\e\*q .Sh DIAGNOSTICS

\&.\e\*q The next is for sections 2, 3, & 9 only.

\&.\e\*q .Sh ERRORS

\&.\e\*q .Sh SEE ALSO

\&.\e\*q .Xr foobar 1

\&.\e\*q .Sh STANDARDS

\&.\e\*q .Sh HISTORY

\&.\e\*q .Sh AUTHORS

\&.\e\*q .Sh CAVEATS

\&.\e\*q .Sh BUGS

\&.\e\*q .Sh SECURITY CONSIDERATIONS

.Ed

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

.Pp

Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,

but non-compulsory.

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

.Sh MACRO SYNTAX

Every line beginning with the control character

Macros are one to three three characters in length and begin with a

.Sq \.

control character ,

is processed for macros, two- or three-character sequences.

.Sq \&. ,

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

at the beginning of the line. An arbitrary amount of whitespace may

sit between the control character and the macro name. Thus,

.Sq \&.Pp

and

.Sq \&.\ \ \ \&Pp

are equivalent. Macro names are two or three characters in length.

.Pp

The syntax of a macro depends on its classification. In this section,

.Sq \-arg

Line 237 parameters;

Line 290 parameters;

opens the scope of a macro; and if specified,

.Sq \&Yc

closes it out.

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

.Pp

The

.Em Callable

column indicates that the macro may be called subsequent to the initial

line-macro. If a macro is not callable, then its invocation after the

initial line macro is interpreted as opaque text, such that

.Sq \&.Fl Sh

.Sq \&.Fl \&Sh

produces

.Sq Fl Sh .

.Sq Fl \&Sh .

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

.Pp

The

.Em Parsable

column indicates whether the macro may be followed by further

(ostensibly callable) macros. If a macro is not parsable, subsequent

macro invocations on the line will be interpreted as opaque text.

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

.Pp

The

.Em Scope

column, if applicable, describes closure rules.

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

.Ss Block full-explicit

Multi-line scope closed by an explicit closing macro. All macros

contains bodies; only

Line 270 contains a head.

Line 324 contains a head.

\(lBbody...\(rB

\&.Yc

.Ed

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

.Pp

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

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

Line 283 contains a head.

Line 337 contains a head.

.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

Multi-line scope closed by end-of-file or implicitly by another macro.

All macros have bodies; some

Line 301 may have multiple heads.

Line 356 may have multiple heads.

\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB

\(lBbody...\(rB

.Ed

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

.Pp

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

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

Line 310 may have multiple heads.

Line 365 may have multiple heads.

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

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

.El

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

.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 325 and/or tail

Line 381 and/or tail

\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \

\(lBbody...\(rB \&Yc \(lBtail...\(rB

.Ed

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

.Pp

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

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

Line 354 and/or tail

Line 410 and/or tail

.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

Like block full-implicit, but with single-line scope closed by

.Sx Reserved Characters

Line 362 or end of line.

Line 419 or end of line.

.Bd -literal -offset indent

\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB

.Ed

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

.Pp

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

.It Em Macro Ta Em Callable Ta Em Parsable

Line 378 or end of line.

Line 435 or end of line.

.It \&Qq Ta Yes Ta Yes

.It \&Sq Ta Yes Ta Yes

.El

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

.Ss In-line

Closed by

.Sx Reserved Characters ,

Line 394 then the macro accepts an arbitrary number of argument

Line 452 then the macro accepts an arbitrary number of argument

\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN

.Ed

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

.Pp

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

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

Line 430 then the macro accepts an arbitrary number of argument

Line 488 then the macro accepts an arbitrary number of argument

.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 \&Ex Ta \&No Ta \&No Ta n

.It \&Fa Ta Yes Ta Yes Ta n

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

.It \&Fl Ta Yes Ta Yes Ta n

Line 457 then the macro accepts an arbitrary number of argument

Line 515 then the macro accepts an arbitrary number of argument

.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 \&Rv Ta \&No Ta \&No Ta n

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

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

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

Line 470 then the macro accepts an arbitrary number of argument

Line 528 then the macro accepts an arbitrary number of argument

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

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

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

.El

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

.Sh COMPATIBILITY

This section documents compatibility with other roff implementations, at

this time limited to

Line 482 refers to those versions before the

Line 541 refers to those versions before the

.Pa doc.tmac

file re-write

.Pq somewhere between 1.15 and 1.19 .

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

.Pp

.Bl -dash -compact

.\" LIST-ITEM

.It

The

.Sq \-split

Line 495 argument to

Line 553 argument to

.Sq \&An

applies to the whole document, not just to the current section as it

does in groff.

.\" LIST-ITEM

.It

In quoted literals, groff allowed pair-wise double-quotes to produce a

standalone double-quote in formatted output. This idiosyncratic

behaviour is no longer applicable.

.\" LIST-ITEM

.It

The

.Sq \&sp

macro does not accept negative numbers.

.\" LIST-ITEM

.It

Blocks of whitespace are stripped from both macro and free-form text

lines (except when in literal mode), while groff would retain whitespace

in free-form text lines.

.\" LIST-ITEM

.It

Historic groff has many un-callable macros. Most of these (excluding

some block-level macros) are now callable, conforming to the

non-historic groff version.

.\" LIST-ITEM

.It

The vertical bar

.Sq \(ba

made historic groff

.Qq go orbital

but is a proper delimiter in this implementation.

.\" LIST-ITEM

.It

.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

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

of proceeded) is not supported.

.\" LIST-ITEM

.It

The

.Sq \&At

macro only accepts a single parameter.

.\" LIST-ITEM

.It

Some manuals use

.Sq \&Li

incorrectly by following it with a reserved character and expecting the

delimiter to render. This is not supported.

.\" LIST-ITEM

.It

In groff, the

.Sq \&Fo

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

.El

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

.Sh SEE ALSO

.Xr mandoc 1 ,

.Xr mandoc_char 7

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

.Sh AUTHORS

The

.Nm

reference was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

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

.Sh CAVEATS

There are many ambiguous parts of mdoc.

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

.Pp

.Bl -dash -compact

.\" LIST-ITEM

.It

.Sq \&Fa

should be

.Sq \&Va

as function arguments are variables.

.\" LIST-ITEM

.It

.Sq \&Ft

should be

Line 584 should be removed and

Line 633 should be removed and

.Sq \&Fo ,

which ostensibly follows it, should follow the same convention as

.Sq \&Va .

.\" LIST-ITEM

.It

.Sq \&Va

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

variable name and optional, preceding type.

.\" LIST-ITEM

.It

.Sq \&Fd

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

synopsis section.

.Sq \&In

should be used, instead.

.\" LIST-ITEM

.It

Only the

.Sq \-literal

argument to

.Sq \&Bd

makes sense. The remaining ones should be removed.

.\" LIST-ITEM

.It

The

.Sq \&Xo

and

.Sq \&Xc

macros should be deprecated.

.\" LIST-ITEM

.It

The

.Sq \&Dt

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

render when formatting the manual page.

.\" LIST-ITEM

.It

.Sq \&Lx

Line 624 should be provided for Linux (\(`a la

Line 667 should be provided for Linux (\(`a la

.Sq \&Ox ,

.Sq \&Nx

etc.).

.\" LIST-ITEM

.It

There's no way to refer to references in

.Sq \&Rs/Re

blocks.

.\" LIST-ITEM

.It

The \-split and \-nosplit dictates via

.Sq \&An

are re-set when entering and leaving the AUTHORS section.

.El

CVSweb