mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.110 and 1.118

version 1.110, 2010/05/26 10:39:35

version 1.118, 2010/06/04 21:49:39

Line 33 section describes compatibility with other troff \-mdo

.Pp

.Nm

document follows simple rules: lines beginning with the control

character

.Sq \.

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

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

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

respectively) may be used instead.

A text decoration is valid within

the current font scope only: if a macro opens a font scope alongside

its own scope, such as

.Sx \&Bf

.Cm \&Sy ,

Line 343 file:

\&.Dd $\&Mdocdate$

\&.Dt mdoc 7

\&.Os

\&.

\&.Sh NAME

\&.Nm foo

\&.Nd a description goes here

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

\&.\e\*q .Sh LIBRARY

\&.

\&.Sh SYNOPSIS

\&.Nm foo

\&.Op Fl options

\&.Ar

\&.

\&.Sh DESCRIPTION

The

\&.Nm

Line 1139 macro.

Line 1136 macro.

These dictate the width of columns either as

.Sx Scaling Widths

or literal text.

List entry bodies must be left empty.

If the initial macro of a

Column bodies have the following syntax:

.Fl column

.Pp

list is not an

.D1 .It col1 <TAB> ... coln

.Sx \&It ,

.D1 .It col1 Ta ... coln

.D1 .It col1 <TAB> col2 Ta coln

.Sx \&It

.Pp

context spanning each line is implied until an

where columns may be separated by tabs, the literal string

.Sx \&It

.Qq Ta ,

line macro is encountered, at which point list bodies are interpreted as

or a mixture of both.

described in the

These are equivalent except that quoted sections propogate over tabs,

.Sx \&It

for example,

documentation.

.Pp

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;

.Pp

will preserve the semicolon whitespace except for the last.

.It Fl dash

A list offset by a dash (hyphen).

The head of list entries must be empty.

Line 1209 after the head as specified by the

Line 1202 after the head as specified by the

.Fl width

argument.

.El

.Pp

See also

.Sx \&It .

.Ss \&Bo

Begins a block enclosed by square brackets.

Does not have any head arguments.

Line 1336 See also

Line 1332 See also

and

.Sx \&Dl .

.Ss \&Db

Start a debugging context.

This macro is parsed, but generally ignored.

Its calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Db Cm on | off

.Ss \&Dc

Closes a

.Sx \&Do

Line 1408 This is the mandatory second macro of any

Line 1409 This is the mandatory second macro of any

file.

Its calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch

.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch

.Pp

Its arguments are as follows:

.Bl -tag -width Ds -offset Ds

.It Cm title

The document's title (name).

The document's title (name), defaulting to

This should be capitalised and is required.

.Qq UNKNOWN

if unspecified.

It should be capitalised.

.It Cm section

The manual section.

This may be one of

Line 1451 This may be one of

Line 1454 This may be one of

.Ar paper

.Pq paper .

It is also required and should correspond to the manual's filename

It should correspond to the manual's filename suffix and defaults to

suffix.

.Qq 1

if unspecified.

.It Cm volume

This overrides the volume inferred from

.Ar section .

Line 1524 Examples:

Line 1528 Examples:

.D1 \&.Dt FOO 1

.D1 \&.Dt FOO 4 KM

.D1 \&.Dt FOO 9 i386

.D1 \&.Dt FOO 9 KM i386

.Pp

See also

.Sx \&Dd

Line 1561 and

Line 1564 and

.Ss \&Ef

.Ss \&Ek

.Ss \&El

Ends a list context started by

.Sx \&Bl .

.Pp

See also

.Sx \&Bl

and

.Sx \&It .

.Ss \&Em

Denotes text that should be emphasised.

Note that this is a presentation term and should not be used for

Line 1600 is not provided, the document's name as stipulated in

Line 1610 is not provided, the document's name as stipulated in

.Sx \&Nm

is provided.

.Ss \&Fa

Function argument.

This may be invoked for names with or without the corresponding type.

It is also used to specify the field name of a structure.

Most often, the

.Sx \&Fa

macro is used in the

.Em SYNOPSIS

section when documenting multi-line function prototypes.

If invoked with multiple arguments, the arguments are separated by a

comma.

Furthermore, if the following macro is another

.Sx \&Fa ,

the last argument will also have a trailing comma.

.Pp

Examples:

.D1 \&.Fa \(dqconst char *p\(dq

.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq

.D1 \&.Fa foo

.Ss \&Fc

.Ss \&Fd

Historically used to document include files.

This usage has been deprecated in favour of

.Sx \&In .

Do not use this macro.

.Pp

See also

.Sx \&In .

.Ss \&Fl

Command-line flag.

Used when listing arguments to command-line utilities.

Line 1644 and

Line 1679 and

.Ss \&Hf

.Ss \&Ic

.Ss \&In

.Qq include

file.

In the

.Em SYNOPSIS

section (only if invoked as the line macro), the first argument is

preceded by

.Qq #include ,

the arguments is enclosed in angled braces, and a newline is asserted.

In all other invocations, only angled braces will enclose the argument.

.Pp

Examples

.D1 \&.In sys/types

.Ss \&It

A list item. The syntax of this macro depends on the list type.

.Pp

Lists

of type

.Fl hang ,

.Fl ohang ,

.Fl inset ,

and

.Fl diag

have the following calling syntax:

.Pp

.D1 \. Ns Sx \&It Cm args

.Pp

Lists of type

.Fl bullet ,

.Fl dash ,

.Fl enum ,

.Fl hyphen

and

.Fl item

have the following calling syntax:

.Pp

.D1 \. Ns Sx \&It

.Pp

with subsequent lines interpreted within the scope of the

.Sx \&It

until either a closing

.Sx \&El

or another

.Sx \&It .

.Pp

The

.Fl tag

list has syntax

.Pp

.D1 \. Ns Sx \&It Op Cm args

.Pp

with subsequent lines interpreted as with

.Fl bullet

and family.

The line arguments correspond to the list's left-hand side; body

arguments correspond to the list's contents.

.Pp

The

.Fl column

list is the most complicated.

Its syntax is

.Pp

.D1 \. Ns Sx \&It Op Cm args

.Pp

where

.Cm args

are phrases, a mix of macros and text corresponding to a line column,

delimited by tabs or the special

.Sq \&Ta

pseudo-macro.

Lines subsequent the

.Sx \&It

are interpreted within the scope of the last phrase.

Calling the pseudo-macro

.Sq \&Ta

will open a new phrase scope (this must occur on a macro line to be

interpreted as a macro). Note that the tab phrase delimiter may only be

used within the

.Sx \&It

line itself.

Subsequent this, only the

.Sq \&Ta

pseudo-macro may be used to delimit phrases.

Furthermore, note that quoted sections propogate over tab-delimited

phrases on an

.Sx \&It ,

for example,

.Pp

.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;

.Pp

will preserve the semicolon whitespace except for the last.

.Pp

See also

.Sx \&Bl .

.Ss \&Lb

Specify a library.

The calling syntax is as follows:

Line 1684 See also

Line 1812 See also

.Ss \&Lp

.Ss \&Ms

.Ss \&Mt

Format a

.Qq mailto:

hyperlink.

The calling syntax is as follows:

.Pp

.D1 \. Ns Sx \&Mt Cm address

.Pp

Examples:

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

.Ss \&Nd

.Ss \&Nm

.Ss \&No

Line 1910 Heirloom troff, the other significant troff implementa

Line 2047 Heirloom troff, the other significant troff implementa

\-mdoc, is similar to historic groff.

.Pp

.Bl -dash -compact

.It

Historic groff formats the

.Sx \&In

badly: trailing arguments are trashed and

.Em SYNOPSIS

is not specially treated.

.It

groff does not accept the

.Sq \&Ta

pseudo-macro as a line macro.

mandoc does.

.It

The comment syntax

.Sq \e."

CVSweb