mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.198 and 1.207

version 1.198, 2011/08/16 23:37:39

version 1.207, 2011/08/30 13:14:01

Line 30 language is used to format

manuals.

This reference document describes its syntax, structure, and

usage.

The reference implementation is

The reference implementation for

.Nm

formatting is

.Xr mandoc 1 ;

the

.Sx COMPATIBILITY

section describes compatibility with other troff \-mdoc implementations.

section describes compatibility with other implementations.

.Pp

.Nm

Line 42 document follows simple rules: lines beginning with th

Line 44 document follows simple rules: lines beginning with th

character

.Sq \&.

are parsed for macros.

Text lines, those not beginning with the control character, are

Lines not beginning with the control character are

interpreted within the scope of prior macros:

.Bd -literal -offset indent

\&.Sh Macro lines change control state.

Line 52 Text lines are interpreted within the current state.

Line 54 Text lines are interpreted within the current state.

.Nm

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

character, and, in certain circumstances, the tab character.

.Pp

The back-space character

If the first character of a text line is a space, that line is printed

.Sq \e

with a leading newline.

indicates the start of an escape sequence for

.Sx Comments ,

.Sx Predefined Strings ,

and

.Sx Special Characters .

.Ss Comments

Text following a

Text following an escaped double-quote

.Sq \e\*q ,

.Sq \e\(dq ,

whether in a macro or text line, is ignored to the end of

line.

A macro line with only a control character and comment escape,

A macro line beginning with a control character and comment escape

.Sq \&.\e\*q ,

.Sq \&.\e\(dq

is also ignored.

Macro lines with only a control character and optional whitespace are

Furthermore,

macro lines with only a control character and optional trailing

whitespace are

stripped from input.

.Pp

Examples:

.Bd -literal -offset indent -compact

\&.\e\(dq This is a comment line.

\&.\e\(dq The next line is ignored:

\&.

\&.Em Emphasis \e\(dq This is also a comment.

.Ed

.Ss Special Characters

Special characters may occur in both macro and text lines.

Special characters are used to encode special glyphs and are rendered

differently across output media.

They may occur in both macro and text lines.

Sequences begin with the escape character

.Sq \e

followed by either an open-parenthesis

Line 76 for two-character sequences; an open-bracket

Line 94 for two-character sequences; an open-bracket

for n-character sequences (terminated at a close-bracket

.Sq \&] ) ;

or a single one character sequence.

.Pp

Examples:

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

.It Li \e(em

Two-letter em dash escape.

.It Li \ee

One-letter backslash escape.

.El

.Pp

See

.Xr mandoc_char 7

for a complete list.

Examples include

.Sq \e(em

.Pq em-dash

and

.Sq \ee

.Pq back-slash .

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

escape followed by an indicator: B (bold), I (italic), R (Roman), or P

escape followed by an indicator: B (bold), I (italic), R (regular), or P

(revert to previous mode):

(revert to previous mode).

.Pp

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

.Dl \efBbold\efR \efIitalic\efP

.Pp

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

respectively) may be used instead.

If a macro opens a font scope after calling

.Sq \ef ,

Line 105 mode will be restored upon exiting the

Line 123 mode will be restored upon exiting the

.Sx \&Bf

scope.

.Pp

Note this form is

Examples:

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

.It Li \efBbold\efR

Write in bold, then switch to regular font mode.

.It Li \efIitalic\efP

Write in italic, then return to previous font mode.

.El

.Pp

Text decoration is

.Em not

recommended for

.Nm ,

which encourages semantic annotation.

.Ss Predefined Strings

Historically,

Predefined strings, like

troff

also defined a set of package-specific

.Dq predefined strings ,

which, like

.Sx Special Characters ,

mark special output characters and strings by way of input codes.

mark special output glyphs.

Predefined strings are escaped with the slash-asterisk,

.Sq \e* :

single-character

Line 126 two-character

Line 148 two-character

.Sq \e*(XX ,

and N-character

.Sq \e*[N] .

See

.Pp

.Xr mandoc_char 7

Examples:

for a complete list.

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

Examples include

.It Li \e*(Am

.Sq \e*(Am

Two-letter ampersand predefined string.

.Pq ampersand

.It Li \e*q

and

One-letter double-quote predefined string.

.Sq \e*(Ba

.El

.Pq vertical bar .

.Pp

These strings are set using

.Xr roff 7 ,

although

.Nm

consists of several pre-set escapes listed in

.Xr mandoc_char 7 .

.Ss Whitespace

Whitespace consists of the space character.

In text lines, whitespace is preserved within a line; unescaped

In text lines, whitespace is preserved within a line.

trailing spaces are stripped from input (unless in a literal context).

In macro lines, whitespace delimits arguments and is discarded.

Blank text lines, which may include whitespace, are only permitted

within literal contexts.

.Pp

In general, trailing whitespace on input lines is discouraged

Unescaped trailing spaces are stripped from text line input unless in a

for reasons of clarity and portability.

literal context.

In general, trailing whitespace on any input line is discouraged for

reasons of portability.

In the rare case that a blank character is needed at the end of an

input line, it may be forced by

.Sq \e\ \e& .

.Pp

In macro lines, whitespace delimits arguments and is discarded.

In general, space characters can be rendered as literal

characters by using non-breaking space escapes or

.Sx Quotation .

.Pp

Blank text lines, which may include whitespace, are only permitted

within literal contexts.

If the first character of a text line is a space, that line is printed

with a leading newline.

.Ss Quotation

Macro arguments may be quoted with double-quotes; in this case,

Macro arguments may be quoted with double-quotes to so that the

whitespace within the quotes is retained as part of the argument.

enclosed text is one literal term.

For example,

Quoted text, even if whitespace or if it would cause a macro invocation

when unquoted, is considered literal text.

.Pp

.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"

.Pp

renders as

.Sq Fn strlen "const char *s" ,

while

.Pp

.D1 Pf \. \&Fn strlen "const char *s"

.Pp

would produce

.Sq Fn strlen const char *s .

.Pp

A quoted argument begins with a double-quote preceded by whitespace.

The next double-quote not pairwise adjacent to another double-quote

terminates the literal, regardless of surrounding whitespace.

.Pp

In unquoted arguments, space characters can alternatively be included

Examples:

by preceding them with a backslash

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

.Pq Sq \e\~ ,

.It Li .Fn strlen \(dqconst char *s\(dq

but quoting is usually better for clarity.

Group arguments

.Pp

.Qq const char *s

Note that any quoted text, even if it would cause a macro invocation

into one function argument.

when unquoted, is considered literal text.

If unspecified,

Thus, the following produces

.Qq const ,

.Sq Op "Fl a" :

.Qq char ,

.Bd -literal -offset indent

and

\&.Op "Fl a"

.Qq *s

.Ed

would be considered separate arguments.

.Pp

.Pq See Sx \&Fn .

In text lines, quotes are regarded as opaque text.

.It Li .Op \(dqFl a\(dq

Consider

.Qq \&Fl a

as literal text instead of a flag macro.

.Pq Aee Sx \&Op , \&Fl .

.El

.Ss Scaling Widths

Many macros support scaled widths for their arguments, such as

Many macros support scaled widths for their arguments.

stipulating a two-inch list indentation with the following:

The syntax for a scaled width is

.Bd -literal -offset indent

\&.Bl -tag -width 2i

.Ed

.Pp

The syntax for scaled widths is

.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,

where a decimal must be preceded or proceeded by at least one digit.

Negative numbers, while accepted, are truncated to zero.

.Pp

The following scaling units are accepted:

.Pp

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

Line 235 or

Line 261 or

is necessarily non-portable across output media.

See

.Sx COMPATIBILITY .

.Pp

Examples:

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

.It Li \&.Bl -tag -width 2i

two-inch tagged list indentation

.Pq see Sx \&Bl

.It Li \&.sp 2v

two vertical spaces

.Pq see Sx \&sp

.El

.Ss Sentence Spacing

When composing a manual, make sure that sentences end at the end of

Sentences should terminate at the end of an input line.

a line.

By doing this, a formatter will be able to apply the proper amount of

By doing so, front-ends will be able to apply the proper amount of

spacing after the end of sentence (unescaped) period, exclamation mark,

or question mark followed by zero or more non-sentence closing

delimiters

Line 251 delimiters

Line 286 delimiters

.Pp

The proper spacing is also intelligently preserved if a sentence ends at

the boundary of a macro line.

For example:

.Pp

.Dl \&.Xr mandoc 1 \&.

Examples:

.Dl \&.Fl T \&Ns \&Cm ascii \&.

.Bd -literal -offset indent -compact

Do not end sentences mid-line like this. Instead,

end a sentence like this.

A macro would end like this:

\&.Xr mandoc 1 \&.

.Ed

.Sh MANUAL STRUCTURE

A well-formed

.Nm

Line 292 file for a utility

Line 331 file for a utility

\&.Sh NAME

\&.Nm progname

\&.Nd one line about what it does

\&.\e\*q .Sh LIBRARY

\&.\e\(dq .Sh LIBRARY

\&.\e\*q For sections 2, 3, & 9 only.

\&.\e\(dq For sections 2, 3, & 9 only.

\&.\e\*q Not used in OpenBSD.

\&.\e\(dq Not used in OpenBSD.

\&.Sh SYNOPSIS

\&.Nm progname

\&.Op Fl options

Line 303 file for a utility

Line 342 file for a utility

The

\&.Nm

utility processes files ...

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

\&.\e\(dq .Sh IMPLEMENTATION NOTES

\&.\e\*q Not used in OpenBSD.

\&.\e\(dq Not used in OpenBSD.

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

\&.\e\(dq .Sh RETURN VALUES

\&.\e\*q For sections 2, 3, & 9 only.

\&.\e\(dq For sections 2, 3, & 9 only.

\&.\e\*q .Sh ENVIRONMENT

\&.\e\(dq .Sh ENVIRONMENT

\&.\e\*q For sections 1, 6, 7, & 8 only.

\&.\e\(dq For sections 1, 6, 7, & 8 only.

\&.\e\*q .Sh FILES

\&.\e\(dq .Sh FILES

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

\&.\e\(dq .Sh EXIT STATUS

\&.\e\*q For sections 1, 6, & 8 only.

\&.\e\(dq For sections 1, 6, & 8 only.

\&.\e\*q .Sh EXAMPLES

\&.\e\(dq .Sh EXAMPLES

\&.\e\*q .Sh DIAGNOSTICS

\&.\e\(dq .Sh DIAGNOSTICS

\&.\e\*q For sections 1, 4, 6, 7, & 8 only.

\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.

\&.\e\*q .Sh ERRORS

\&.\e\(dq .Sh ERRORS

\&.\e\*q For sections 2, 3, & 9 only.

\&.\e\(dq For sections 2, 3, & 9 only.

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

\&.\e\(dq .Sh SEE ALSO

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

\&.\e\(dq .Xr foobar 1

\&.\e\*q .Sh STANDARDS

\&.\e\(dq .Sh STANDARDS

\&.\e\*q .Sh HISTORY

\&.\e\(dq .Sh HISTORY

\&.\e\*q .Sh AUTHORS

\&.\e\(dq .Sh AUTHORS

\&.\e\*q .Sh CAVEATS

\&.\e\(dq .Sh CAVEATS

\&.\e\*q .Sh BUGS

\&.\e\(dq .Sh BUGS

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

\&.\e\(dq .Sh SECURITY CONSIDERATIONS

\&.\e\*q Not used in OpenBSD.

\&.\e\(dq Not used in OpenBSD.

.Ed

.Pp

The sections in an

Line 406 macros should follow C header-file conventions.

Line 445 macros should follow C header-file conventions.

.Pp

And for the third, configurations (section 4):

.Bd -literal -offset indent

\&.Cd \*qit* at isa? port 0x2e\*q

\&.Cd \(dqit* at isa? port 0x2e\(dq

\&.Cd \*qit* at isa? port 0x4e\*q

\&.Cd \(dqit* at isa? port 0x4e\(dq

.Ed

.Pp

Manuals not in these sections generally don't need a

Line 650 contain a head.

Line 689 contain a head.

\(lBbody...\(rB

\&.Yc

.Ed

.Pp

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

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

.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope

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

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

Line 683 has multiple heads.

Line 721 has multiple heads.

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

\(lBbody...\(rB

.Ed

.Pp

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

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

.It Em Macro Ta Em Callable Ta Em Parsed 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

Line 719 and/or tail

Line 756 and/or tail

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

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

.Ed

.Pp

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

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

.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope

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

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

Line 753 end of the line.

Line 789 end of the line.

.Bd -literal -offset indent

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

.Ed

.Pp

.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent

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

.It Em Macro Ta Em Callable Ta Em Parsed

.It Sx \&Aq Ta Yes Ta Yes

.It Sx \&Bq Ta Yes Ta Yes

Line 789 in

Line 824 in

lists.

It delimits blocks representing table cells;

these blocks have bodies, but no heads.

.Pp

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

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

.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope

.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It

.El

Line 808 then the macro accepts an arbitrary number of argument

Line 842 then the macro accepts an arbitrary number of argument

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

.Ed

.Pp

.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent

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

.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments

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

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

Line 2036 If the argument is a macro, a hyphen is prefixed to th

Line 2069 If the argument is a macro, a hyphen is prefixed to th

output.

.Pp

Examples:

.Dl ".Nm cat Fl v No considered harmful"

.Dl ".Fl R Op Fl H | L | P"

.Dl ".Nm cp Fl pR Ar source ... directory"

.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"

.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS"

.Dl ".Fl type Cm d Fl name Pa CVS"

.Dl ".Nm kill Fl Ar signal_number pid"

.Dl ".Fl Ar signal_number"

.Dl ".Nm su Fl"

.Dl ".Fl o Fl"

.Pp