mandoc/man.7 - diff

Return to man.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.15, 2009/06/22 13:09:17

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 the syntax and structure of

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

this language.

usage.

.Pp

.Em \&Do not

.Bf -emphasis

use

Do not use

.Nm

to write your manuals. Use the

to write your manuals.

.Ef

Use the

.Xr mdoc 7

language, instead.

.\" PARAGRAPH

Line 41 language, instead.

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 53 Other lines are interpreted within the current state.

Line 55 Other lines are interpreted within the current state.

.Sh INPUT ENCODING

.Nm

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

space character

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

.Sq \ ,

and tabs

.Sq \et .

All manuals must have

.Ux

.Sq \en

line termination.

.Pp

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

vertical space.

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

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

.Xr mandoc_char 7

for a complete list. Examples include

.Sq \e(em

.Pq em-dash

and

.Sq \ee

.Pq back-slash .

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

.Ss Text Decoration

Terms may be text-decorated using the

.Sq \ef

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

(Roman, or reset).

.\" 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

utility such as

.Xr mandoc 1 .

.\" SECTION

.Sh STRUCTURE

Each

.Nm

document must contain contains at least the

.Sq \&.TH

macro describing the document's section and title. It may occur

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

first macro.

.Pp

Characters may alternatively be escaped by a slash-asterisk,

Beyond the

.Sq \e* ,

.Sq \&.TH ,

with the same combinations as described above. This form is deprecated.

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

.\" SECTION

.Sh SYNTAX

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

Line 108 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 120 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 131 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 156 The

Line 180 The

macro is similar, but does not need an empty argument line to trigger

the behaviour.

.\" SECTION

.Sh STRUCTURE

Each

.Nm

document must contain contains at least the

.Sq \&.TH

macro describing the document's section and title. It may occur

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

.Sh MACROS

This section contains a complete list of all

.Nm

macros and corresponding number of arguments.

.Pp

Line 212 These follow the same calling conventions as the above

Line 223 These follow the same calling conventions as the above

.Nm

macros.

.\" SECTION

.Sh COMPATIBILITY

See

.Xr mdoc 7

for groff compatibility notes.

.\" SECTION

.Sh SEE ALSO

.Xr mandoc 1 ,

.Xr mandoc_char 7

Line 219 macros.

Line 235 macros.

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.\" SECTION

.Sh CAVEATS

CVSweb