mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.142 and 1.146

version 1.142, 2010/07/26 13:45:49

version 1.146, 2010/08/07 10:18:36

Line 28 language is used to format

.Bx

.Ux

manuals.

In this reference document, we describe its syntax, structure, and

This reference document describes its syntax, structure, and

usage.

Our reference implementation is mandoc; the

The reference implementation is

.Xr mandoc 1 ;

the

.Sx COMPATIBILITY

section describes compatibility with other troff \-mdoc implementations.

.Pp

Line 61 line.

Line 63 line.

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

.Sq \&.\e\*q ,

is also ignored.

Macro lines with only a control character and optionally whitespace are

Macro lines with only a control character and optional whitespace are

stripped from input.

.Ss Reserved Characters

Within a macro line, the following characters are reserved:

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

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

.Sq \&[

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

.Sq \&] ) ;

or a single one-character sequence.

or a single one character sequence.

See

.Xr mandoc_char 7

for a complete list.

Line 120 and

Line 122 and

.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 (Roman), or P

(revert to previous mode):

.Pp

.D1 \efBbold\efR \efIitalic\efP

Line 147 recommended for

Line 149 recommended for

which encourages semantic annotation.

.Ss Predefined Strings

Historically,

.Xr groff 1

troff

also defined a set of package-specific

.Dq predefined strings ,

which, like

Line 172 and

Line 174 and

.Pq vertical bar .

.Ss Whitespace

Whitespace consists of the space character.

In free-form lines, whitespace is preserved within a line; un-escaped

In free-form lines, whitespace is preserved within a line; unescaped

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

Blank free-form lines, which may include whitespace, are only permitted

within literal contexts.

Line 183 If arguments are quoted, whitespace within the quotes

Line 185 If arguments are quoted, whitespace within the quotes

Macro arguments may be quoted with double-quotes 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

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

terminates the literal, regardless of surrounding whitespace.

.Pp

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

Line 276 is necessarily non-portable across output media.

Line 278 is necessarily non-portable across output media.

See

.Sx COMPATIBILITY .

.Ss Sentence Spacing

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

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

a line.

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

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

Line 288 delimiters (

Line 290 delimiters (

.Sq \&" ) .

.Pp

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

the boundary of a macro line, e.g.,

the boundary of a macro line.

For example:

.Pp

.D1 \&Xr mandoc 1 \.

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

Line 361 utility processes files ...

Line 364 utility processes files ...

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

.Ed

.Pp

The sections in a

The sections in an

.Nm

document are conventionally ordered as they appear above.

Sections should be composed as follows:

.Bl -ohang -offset Ds

.It Em NAME

The name(s) and a one-line description of the documented material.

The name(s) and a one line description of the documented material.

The syntax for this as follows:

.Bd -literal -offset indent

\&.Nm name0

\&.Nm name0 ,

\&.Nm name1

\&.Nm name1 ,

\&.Nm name2

\&.Nd a one-line description

\&.Nd a one line description

.Ed

.Pp

The

Line 415 generally structured as follows:

Line 418 generally structured as follows:

.Pp

For the second, function calls (sections 2, 3, 9):

.Bd -literal -offset indent

\&.Vt extern const char *global;

\&.In header.h

\&.Vt extern const char *global;

\&.Ft "char *"

\&.Fn foo "const char *src"

\&.Ft "char *"

Line 445 section, particularly

Line 448 section, particularly

and

.Sx \&Ft .

All of these macros are output on their own line.

If two such dissimilar macros are pair-wise invoked (except for

If two such dissimilar macros are pairwise invoked (except for

.Sx \&Ft

before

.Sx \&Fo

Line 471 or

Line 474 or

.Sx \&Ss

macro or the end of an enclosing block, whichever comes first.

.It Em DESCRIPTION

This expands upon the brief, one-line description in

This expands upon the brief, one line description in

.Em NAME .

It usually contains a break-down of the options (if documenting a

It usually contains a breakdown of the options (if documenting a

command), such as:

.Bd -literal -offset indent

The arguments are as follows:

Line 489 Implementation-specific notes should be kept here.

Line 492 Implementation-specific notes should be kept here.

This is useful when implementing standard functions that may have side

effects or notable algorithmic implications.

.It Em RETURN VALUES

This section is the dual of

This section documents the

.Em EXIT STATUS ,

return values of functions in sections 2, 3, and 9.

which is used for commands.

It documents the return values of functions in sections 2, 3, and 9.

.Pp

See

.Sx \&Rv .

Line 513 the file is used (created, modified, etc.).

Line 514 the file is used (created, modified, etc.).

See

.Sx \&Pa .

.It Em EXIT STATUS

Command exit status for section 1, 6, and 8 manuals.

This section documents the

This section is the dual of

command exit status for section 1, 6, and 8 utilities.

.Em RETURN VALUES ,

which is used for functions.

Historically, this information was described in

.Em DIAGNOSTICS ,

a practise that is now discouraged.

Line 526 See

Line 525 See

.It Em EXAMPLES

Example usages.

This often contains snippets of well-formed, well-tested invocations.

Make doubly sure that your examples work properly!

Make sure that examples work properly!

.It Em DIAGNOSTICS

Documents error conditions.

This is most useful in section 4 manuals.

Line 560 section should be used instead.

Line 559 section should be used instead.

See

.Sx \&St .

.It Em HISTORY

The history of any manual without a

A brief history of the subject, including where support first appeared.

.Em STANDARDS

section should be described in this section.

.It Em AUTHORS

Credits to authors, if applicable, should appear in this section.

Credits to the person or persons who wrote the code and/or documentation.

Authors should generally be noted by both name and email address.

.Pp

See

Line 771 If a number (or inequality) of arguments is

Line 768 If a number (or inequality) of arguments is

.Pq n ,

then the macro accepts an arbitrary number of arguments.

.Bd -literal -offset indent

\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb

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

\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...

Line 1161 and

Line 1158 and

argument are equivalent, as are

.Fl symbolic

and

.Cm \&Sy,

.Cm \&Sy ,

and

.Fl literal

and

Line 1395 and

Line 1392 and

.Sx \&Ux .

.Ss \&Bt

Prints

.Dq is currently in beta test.

.Dq is currently in beta test .

.Ss \&Bx

Format the BSD version provided as an argument, or a default value if no

argument is provided.

Line 1927 See also

Line 1924 See also

and

.Sx \&Fo .

.Ss \&Fx

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

Format the

.Fx

version provided as an argument, or a default value

if no argument is provided.

.Pp

Examples:

Line 1956 Examples:

Line 1955 Examples:

.D1 \&.Ic alias

.Pp

Note that using

.Sx \&Bd No Fl literal

.Sx \&Bd Fl literal

.Sx \&D1

is preferred for displaying code; the

Line 2128 Its syntax is as follows:

Line 2127 Its syntax is as follows:

Examples:

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

.Ss \&Nd

A one-line description of the manual's content.

A one line description of the manual's content.

This may only be invoked in the

.Em SYNOPSIS

section subsequent the

Line 2208 See also

Line 2207 See also

and

.Sx \&Sm .

.Ss \&Nx

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

Format the

.Nx

version provided as an argument, or a default value if

no argument is provided.

.Pp

Examples:

Line 2257 any

Line 2258 any

file.

Its syntax is as follows:

.Pp

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

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

.Pp

The optional

.Cm system

Line 2280 Unknown usage.

Line 2281 Unknown usage.

.Em Remarks :

this macro has been deprecated.

.Ss \&Ox

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

Format the

.Ox

version provided as an argument, or a default value

if no argument is provided.

.Pp

Examples:

Line 2600 Examples:

Line 2603 Examples:

.D1 \&.Tn IBM

.Ss \&Ud

Prints out

.Dq currently under development.

.Dq currently under development .

.Ss \&Ux

Format the UNIX name.

Accepts no argument.

Line 2800 Furthermore, the

Line 2803 Furthermore, the

.Sq f

scaling unit, while accepted, is rendered as the default unit.

.It

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

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

standalone double-quote in formatted output.

This idiosyncratic behaviour is not applicable in mandoc.

.It

CVSweb