mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.202 and 1.210

version 1.202, 2011/08/18 08:58:44

version 1.210, 2011/09/18 07:57:16

Line 63 and

.Sx Special Characters .

.Ss Comments

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 beginning with a control character and comment escape

.Sq \&.\e\*q

.Sq \&.\e\(dq

is also ignored.

Furthermore,

macro lines with only a control character and optional trailing

Line 76 stripped from input.

.Pp

Examples:

.Bd -literal -offset indent -compact

\&.\e\*q This is a comment line.

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

\&.\e\*q The next line is ignored:

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

\&.

\&.Em Emphasis \e\*q This is also a comment.

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

.Ed

.Ss Special Characters

Special characters are used to encode special glyphs and are rendered

Line 97 or a single one character sequence.

.Pp

Examples:

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

.It \e(em

.It Li \e(em

em dash

Two-letter em dash escape.

.It \ee

.It Li \ee

backslash

One-letter backslash escape.

.El

.Pp

See

Line 125 scope.

.Pp

Examples:

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

.It \efBbold\efR

.It Li \efBbold\efR

write in bold, then switch to regular

Write in bold, then switch to regular font mode.

.It \efIitalic\efP

.It Li \efIitalic\efP

write in italic, then return to previous

Write in italic, then return to previous font mode.

.El

.Pp

Text decoration is

Line 151 and N-character

.Pp

Examples:

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

.It \e*(Am

.It Li \e*(Am

ampersand

Two-letter ampersand predefined string.

.It \e*(Ba

.It Li \e*q

vertical bar

One-letter double-quote predefined string.

.El

.Pp

These strings are set using

Line 176 In the rare case that a blank character is needed at t

input line, it may be forced by

.Sq \e\ \e& .

.Pp

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.

The syntax for a scaled width is

Line 265 See

Line 264 See

.Pp

Examples:

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

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

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

two-inch tagged list indentation

.Pq see Sx \&Bl

.It \&.sp 2v

.It Li \&.sp 2v

two vertical spaces

.Pq see Sx \&sp

.El

Line 332 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 343 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 446 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 690 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 723 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 759 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 793 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 829 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 848 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 1010 in the same way as a plain

Line 1003 in the same way as a plain

.Sq \&|

character.

Using this predefined string is not recommended in new manuals.

.Sh MACRO OVERVIEW

This overview is sorted such that macros of similar purpose are listed

together, to help find the best macro for any given purpose.

Deprecated macros are not included in the overview, but can be found

in the alphabetical reference below.

.Ss Document preamble and NAME section macros

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Dd Ta document date: Cm $Mdocdate$ | Ar month day , year

.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch

.It Sx \&Os Ta operating system version: Op Ar system Op Ar version

.It Sx \&Nm Ta document name (one argument)

.It Sx \&Nd Ta document description (one line)

.El

.Ss Sections and cross references

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Sh Ta section header (one line)

.It Sx \&Ss Ta subsection header (one line)

.It Sx \&Sx Ta internal cross reference to a section or subsection

.It Sx \&Xr Ta cross reference to another manual page: Ar name section

.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)

.El

.Ss Displays and lists

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Bd , \&Ed Ta display block:

.Fl Ar type

.Op Fl offset Ar width

.Op Fl compact

.It Sx \&D1 Ta indented display (one line)

.It Sx \&Dl Ta indented literal display (one line)

.It Sx \&Bl , \&El Ta list block:

.Fl Ar type

.Op Fl width Ar val

.Op Fl offset Ar val

.Op Fl compact

.It Sx \&It Ta list item (syntax depends on Fl Ar type )

.It Sx \&Ta Ta table cell separator in Sx Bl Fl column No lists

.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)

.El

.Ss Spacing control

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Pf Ta prefix, no following horizontal space (one argument)

.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)

.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)

.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off

.It Sx \&Bk , \&Ek Ta keep block: Fl words

.It Sx \&br Ta force output line break in text mode (no arguments)

.It Sx \&sp Ta force vertical space: Op Ar height

.El

.Ss Semantic markup for command line utilities:

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility

.It Sx \&Fl Ta command line options (flags) (>=0 arguments)

.It Sx \&Cm Ta command modifier (>0 arguments)

.It Sx \&Ar Ta command arguments (>=0 arguments)

.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)

.It Sx \&Ic Ta internal or interactive command (>0 arguments)

.It Sx \&Ev Ta environmental variable (>0 arguments)

.It Sx \&Pa Ta file system path (>=0 arguments)

.El

.Ss Semantic markup for function libraries:

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Lb Ta function library (one argument)

.It Sx \&In Ta include file (one argument)

.It Sx \&Ft Ta function type (>0 arguments)

.It Sx \&Fo , \&Fc Ta function block: Ar funcname

.It Sx \&Fn Ta function name:

.Op Ar functype

.Ar funcname

.Oo

.Op Ar argtype

.Ar argname

.Oc

.It Sx \&Fa Ta function argument (>0 arguments)

.It Sx \&Vt Ta variable type (>0 arguments)

.It Sx \&Va Ta variable name (>0 arguments)

.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)

.It Sx \&Er Ta error constant (>0 arguments)

.It Sx \&Ev Ta environmental variable (>0 arguments)

.El

.Ss Various semantic markup:

.Bl -column "Brq, Bro, Brc" description

.It Sx \&An Ta author name (>0 arguments)

.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name

.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address

.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)

.It Sx \&Ad Ta memory address (>0 arguments)

.It Sx \&Ms Ta mathematical symbol (>0 arguments)

.It Sx \&Tn Ta tradename (>0 arguments)

.El

.Ss Physical markup

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)

.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)

.It Sx \&Li Ta typewriter font (literal) (>0 arguments)

.It Sx \&No Ta return to roman font (normal) (no arguments)

.It Sx \&Bf , \&Ef Ta font block:

.Op Fl Ar type | Cm \&Em | \&Li | \&Sy

.El

.Ss Physical enclosures

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text

.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text

.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text

.It Sx \&Ql Ta single-quoted literal text: Ql text

.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text

.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text

.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text

.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text

.It Sx \&Eo , \&Ec Ta generic enclosure

.El

.Ss Text production

.Bl -column "Brq, Bro, Brc" description

.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...

.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...

.It Sx \&St Ta reference to a standards document (one argument)

.It Sx \&Ux Ta Ux

.It Sx \&At Ta At

.It Sx \&Bx Ta Bx

.It Sx \&Bsx Ta Bsx

.It Sx \&Nx Ta Nx

.It Sx \&Fx Ta Fx

.It Sx \&Ox Ta Ox

.It Sx \&Dx Ta Dx

.El

.Sh REFERENCE

This section is a canonical reference of all macros, arranged

alphabetically.

Line 2103 section, this macro starts a new output line,

Line 2220 section, this macro starts a new output line,

and a blank line is automatically inserted between function definitions.

.Pp

Examples:

.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q

.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq

.Dl \&.Fn funcname \*qint arg0\*q

.Dl \&.Fn funcname \(dqint arg0\(dq

.Dl \&.Fn funcname arg0

.Pp

.Bd -literal -offset indent -compact

Line 2309 line itself; on following lines, only the

Line 2426 line itself; on following lines, only the

.Sx \&Ta

macro can be used to delimit cells, and

.Sx \&Ta

is only recognized as a macro when called by other macros,

is only recognised as a macro when called by other macros,

not as the first macro on a line.

.Pp

Note that quoted strings may span tab-delimited cells on an

Line 2369 Its syntax is as follows:

Line 2486 Its syntax is as follows:

.D1 Pf \. Sx \&Lk Ar uri Op Ar name

.Pp

Examples:

.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q

.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq

.Dl \&.Lk http://bsd.lv

.Pp