mandoc/man.7 - diff

Return to man.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.7 between version 1.19 and 1.21

version 1.19, 2009/07/14 15:56:44

version 1.21, 2009/07/27 12:35:53

Line 25

.Sh DESCRIPTION

The

.Nm man

language was historically used to format

.Ux

manuals. This reference document describes its syntax, structure, and

usage.

.Pp

.Bf Em

.Bf -emphasis

Do not use

.Nm

to write your manuals.

.Ef

Use the

.Xr mdoc 7

Line 43 language, instead.

.Nm

document follows simple rules: lines beginning with the control

character

.Sq \&.

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

prior macros:

Line 57 Other lines are interpreted within the current state.

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

space character, and the tabs character. All manuals must have

.Ux

line termination.

.Pp

Blank lines are acceptable; where found, the output will assert a

vertical space.

Line 70 documents; if encountered at the end of a word, it ens

subsequent word isn't off-set by whitespace.

.\" SUB-SECTION

.Ss Comments

Anything following a

Text following a

.Sq \e"

.Sq \e" ,

delimiter is considered a comment (unless the

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

.Sq \e

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

itself has been escaped) and is ignored to the end of line.

.Sq \&.\e" ,

Furthermore, a macro line with only a control character

is also ignored.

.Sq \. ,

optionally followed by whitespace, is ignored.

.\" SUB-SECTION

.Ss Special Characters

Special character sequences begin with the escape character

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

Sequences begin with the escape character

.Sq \e

followed by either an open-parenthesis

.Sq \&(

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

.Pp

.Xr mandoc_char 7

Characters may alternatively be escaped by a slash-asterisk,

for a complete list. Examples include

.Sq \e* ,

.Sq \e(em

with the same combinations as described above.

.Pq em-dash

.Pp

and

Terms may also be text-decorated using the

.Sq \ee

.Pq back-slash .

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

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

escape followed by a text-decoration letter: B (bold), I, (italic), or P

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

and R (Roman, or reset).

(Roman, or reset).

.\" SUB-SECTION

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

.Ss Whitespace

Unless specifically escaped, consecutive blocks of whitespace are pruned

from input. These are later re-added, if applicable, by a front-end

Line 114 macro describing the document's section and title. It

Line 117 macro describing the document's section and title. It

anywhere in the document, although conventionally, it appears as the

first macro.

.Pp

Beyond the

.Sq \&.TH ,

at least one macro or text node must appear in the document.

.\" SECTION

Line 129 and

Line 132 and

.Sq \&.\ \ \ \&PP

are equivalent.

.Pp

All

.Nm

macros follow the same structural rules:

.Bd -literal -offset indent

\&.YO \(lBbody...\(rB

.Ed

.Pp

The

Line 141 The

Line 144 The

consists of zero or more arguments to the macro.

.Pp

.Nm

has a primitive notion of multi-line scope for the following macros:

.Sq \&.TM ,

.Sq \&.SM ,

.Sq \&.SB ,

Line 152 has a primitive notion of multi-line scope for the fol

Line 155 has a primitive notion of multi-line scope for the fol

.Sq \&.R ,

.Sq \&.B ,

.Sq \&.I ,

.Sq \&.IR

and

.Sq \&.RI .

When these macros are invoked without arguments, the subsequent line is

considered a continuation of the macro. Thus:

.Bd -literal -offset indent

\&.RI

foo

.Ed

.Pp

is equivalent to

.Sq \&.RI foo .

If two consecutive lines exhibit the latter behaviour,

an error is raised. Thus, the following is not acceptable:

.Bd -literal -offset indent

\&.RI

\&.I

Hello, world.

.Ed

.Pp

Line 178 macro is similar, but does not need an empty argument

Line 181 macro is similar, but does not need an empty argument

the behaviour.

.\" SECTION

.Sh MACROS

This section contains a complete list of all

.Nm

macros and corresponding number of arguments.

.Pp

Line 232 for groff compatibility notes.

Line 235 for groff compatibility notes.

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.\" SECTION

.Sh CAVEATS

CVSweb