mandoc/roff.7 - diff

Return to roff.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/roff.7 between version 1.85 and 1.100

version 1.85, 2017/06/06 15:03:35

version 1.100, 2018/08/18 21:37:01

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 86 character, and, in certain circumstances, the tab char

The backslash character

.Sq \e

indicates the start of an escape sequence, used for example for

.Sx Comments ,

.Sx Comments

.Sx Special Characters ,

.Sx Predefined Strings ,

and

user-defined strings defined using the

.Sx Special Characters .

.Sx ds

request.

For a listing of escape sequences, consult the

.Sx ESCAPE SEQUENCE REFERENCE

below.

Line 169 Text decoration is

Line 165 Text decoration is

recommended for

.Xr mdoc 7 ,

which encourages semantic annotation.

.Ss Predefined Strings

Predefined strings, like

.Sx Special Characters ,

mark special output glyphs.

Predefined strings are escaped with the slash-asterisk,

.Sq \e* :

single-character

.Sq \e*X ,

two-character

.Sq \e*(XX ,

and N-character

.Sq \e*[N] .

.Pp

Examples:

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

.It Li \e*(Am

Two-letter ampersand predefined string.

.It Li \e*q

One-letter double-quote predefined string.

.El

.Pp

Predefined strings are not recommended for use,

as they differ across implementations.

Those supported by

.Xr mandoc 1

are listed in

.Xr mandoc_char 7 .

Manuals using these predefined strings are almost certainly not portable.

.Ss Whitespace

Whitespace consists of the space character.

In text lines, whitespace is preserved within a line.

Line 206 Unescaped trailing spaces are stripped from text line

Line 174 Unescaped trailing spaces are stripped from text line

literal context.

In general, trailing whitespace on any input line is discouraged for

reasons of portability.

In the rare case that a blank character is needed at the end of an

In the rare case that a space character is needed at the end of an

input line, it may be forced by

.Sq \e\ \e& .

.Pp

Line 412 Create an alias for a number register.

Line 380 Create an alias for a number register.

Currently unsupported.

.It Ic \&als Ar newname oldname

Create an alias for a request, string, macro, or diversion.

Currently unsupported.

.It Ic \&am Ar macroname Op Ar endmacro

Append to a macro definition.

The syntax of this request is the same as that of

Line 530 input lines without filling.

Line 497 input lines without filling.

.Ar N

defaults to 1.

An argument of 0 or less ends centering.

Currently, high level macros abort certering.

Currently, high level macros abort centering.

.It Ic \&cf Ar filename

Output the contents of a file.

Ignored because insecure.

Line 666 produces

Line 633 produces

.Pp

in the input stream, and thus in the output: \fI\^XtFree\^\fP.

Each occurrence of \e\e$* is replaced with all the arguments,

joined together with single blank characters.

joined together with single space characters.

.Pp

Since macros and user-defined strings share a common string table,

defining a macro

Line 923 The following

Line 890 The following

.Ar font

arguments are supported:

.Bl -tag -width 4n -offset indent

.It Cm B , BI , 3 , 4

.It Cm B , BI , CB , 3 , 4

switches to

.Sy bold

font

.It Cm I , 2

.It Cm I , CI , 2

switches to

.Em underlined

font

.It Cm R , CW , 1

.It Cm R , CR , CW , 1

switches to normal font

.It Cm P No "or no argument"

switches back to the previous font

Line 1045 If the first character of

Line 1012 If the first character of

.Sq c

.Pq character available ,

.Sq d

.Pq string defined ,

.Sq e

.Pq even page ,

.Sq t

Line 1059 it evaluates to false.

Line 1024 it evaluates to false.

If the first character of

.Ar condition

.Sq d ,

it evaluates to true if the rest of

.Ar condition

is the name of an existing user defined macro or string;

otherwise, it evaluates to false.

.It

If the first character of

.Ar condition

.Sq r ,

it evaluates to true if the rest of

.Ar condition

Line 1340 Currently unsupported.

Line 1314 Currently unsupported.

Temporarily turn off line numbering.

Currently unsupported.

.It Ic \&nop Ar body

Execute the rest of the input line as a request or macro line.

Execute the rest of the input line as a request, macro, or text line,

Currently unsupported.

skipping the

.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression

.Ic \&nop

request and any space characters immediately following it.

This is mostly used to indent text lines inside macro definitions.

.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize

Define or change a register.

A register is an arbitrary string value that defines some sort of state,

which influences parsing and/or formatting.

Line 1354 below.

Line 1331 below.

If it is prefixed by a sign, the register will be

incremented or decremented instead of assigned to.

.Pp

The

.Ar stepsize

is used by the

.Ic \en+

auto-increment feature.

It remains unchanged when omitted while changing an existing register,

and it defaults to 0 when defining a new register.

.Pp

The following

.Ar register

is handled specially:

Line 1435 Currently ignored.

Line 1420 Currently ignored.

Print all number registers on standard error output.

Currently ignored.

.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset

Set horizontal page offset.

Set a horizontal page offset.

Currently ignored.

If no argument is specified, the page offset is reverted to its

previous value.

If a sign is specified, the new page offset is calculated relative

to the current one; otherwise, it is absolute.

The argument follows the syntax of

.Sx Scaling Widths

and the default scaling unit is

.Cm m .

.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size

Change point size.

Currently ignored.

Line 1458 This is a groff extension and currently ignored.

Line 1450 This is a groff extension and currently ignored.

.It Ic \&rchar Ar glyph ...

Remove glyph definitions.

Currently unsupported.

.It Ic \&rd Op Ar prompt Op Ar agument ...

.It Ic \&rd Op Ar prompt Op Ar argument ...

Read from standard input.

Currently ignored.

.It Ic \&recursionlimit Ar maxrec maxtail

Line 1477 This is a Heirloom extension and currently ignored.

Line 1469 This is a Heirloom extension and currently ignored.

Justify the next

.Ar N

input lines to the right margin without filling.

Currently ignored.

.Ar N

defaults to 1.

An argument of 0 or less ends right adjustment.

.It Ic \&rm Ar macroname

Remove a request, macro or string.

.It Ic \&rn Ar oldname newname

Rename a request, macro, diversion, or string.

Currently unsupported.

.Xr mandoc 1 ,

user-defined macros,

.Xr mdoc 7

and

.Xr man 7

macros, and user-defined strings can be renamed, but renaming of

predefined strings and of

.Nm

requests is not supported, and diversions are not implemented at all.

.It Ic \&rnn Ar oldname newname

Rename a number register.

Currently unsupported.

Line 1774 logical and (corresponds to C

Line 1777 logical and (corresponds to C

.Ic && )

.It Ic \&:

logical or (corresponds to C

.Ic \&|| )

.Ic || )

.It Ic <?

minimum (not available in C)

.It Ic >?

Line 1816 is an unpaddable space-sized non-breaking space charac

Line 1819 is an unpaddable space-sized non-breaking space charac

.Ss \e\(dq

The rest of the input line is treated as

.Sx Comments .

.Ss \e#

Line continuation with comment.

Discard the rest of the physical input line and continue the logical

input line on the next physical input line, joining the text on

both lines together as if it were on a single input line.

This is a groff extension.

.Ss \e%

Hyphenation allowed at this point of the word; ignored by

.Xr mandoc 1 .

Line 1830 instead.

Line 1839 instead.

.Sx Special Characters

with two-letter names, see

.Xr mandoc_char 7 .

.Ss \e*[ Ns Ar name ]

.Ss \e* Ns Bq Ar name

Interpolate the string with the

.Ar name ;

.Ar name .

see

.Sx Predefined Strings

and

.Sx ds .

For short names, there are variants

.No \e* Ns Ar c

and

.No \e*( Ns Ar cc .

.Pp

One string is predefined on the

.Nm

language level: \e*(.T expands to the name of the output device,

for example ascii, utf8, ps, pdf, html, or markdown.

.Pp

Macro sets traditionally predefine additional strings which are not

portable and differ across implementations.

Those supported by

.Xr mandoc 1

are listed in

.Xr mandoc_char 7 .

.Pp

Strings can be defined, changed, and deleted with the

.Ic \&ds ,

.Ic \&as ,

and

.Ic \&rm

requests.

.Ss \e,

Left italic correction (groff extension); ignored by

.Xr mandoc 1 .

Line 1850 Special character

Line 1874 Special character

.Ss \e/

Right italic correction (groff extension); ignored by

.Xr mandoc 1 .

.Ss \e[ Ns Ar name ]

.Ss \e Ns Bq Ar name

.Sx Special Characters

with names of arbitrary length, see

.Xr mandoc_char 7 .

Line 1906 Move down by half a line; ignored by

Line 1930 Move down by half a line; ignored by

.Xr mandoc 1 .

.Ss \ee

Backslash special character.

.Ss \eF[ Ns Ar name ]

.Ss \eF Ns Bq Ar name

Switch font family (groff extension); ignored by

.Xr mandoc 1 .

For short names, there are variants

.No \eF Ns Ar c

and

.No \eF( Ns Ar cc .

.Ss \ef[ Ns Ar name ]

.Ss \ef Ns Bq Ar name

Switch to the font

.Ar name ,

see

Line 1922 For short names, there are variants

Line 1946 For short names, there are variants

.No \ef Ns Ar c

and

.No \ef( Ns Ar cc .

.Ss \eg[ Ns Ar name ]

.Ss \eg Ns Bq Ar name

Interpolate the format of a number register; ignored by

.Xr mandoc 1 .

For short names, there are variants

Line 1932 and

Line 1956 and

.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq

Set the height of the current font; ignored by

.Xr mandoc 1 .

.Ss \eh\(aq Ns Ar width Ns \(aq

.Ss \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns \(aq

Horizontal motion relative to the current position.

Horizontal motion.

If the vertical bar is given, the motion is relative to the current

indentation.

Otherwise, it is relative to the current position.

The default scaling unit is

.Cm m .

.Ss \ek[ Ns Ar name ]

.Ss \ek Ns Bq Ar name

Mark horizontal input place in register; ignored by

.Xr mandoc 1 .

For short names, there are variants

Line 1951 Draw a horizontal line of

Line 1978 Draw a horizontal line of

.Ar width

using the glyph

.Ar c .

.Ss \eM[ Ns Ar name ]

.Ss \eM Ns Bq Ar name

Set fill (background) color (groff extension); ignored by

.Xr mandoc 1 .

For short names, there are variants

.No \eM Ns Ar c

and

.No \eM( Ns Ar cc .

.Ss \em[ Ns Ar name ]

.Ss \em Ns Bq Ar name

Set glyph drawing color (groff extension); ignored by

.Xr mandoc 1 .

For short names, there are variants

Line 1969 and

Line 1996 and

Character

.Ar number

on the current font.

.Ss \en[ Ns Ar name ]

.Ss \en Ns Oo +|- Oc Ns Bq Ar name

Interpolate the number register

.Ar name .

For short names, there are variants

.No \en Ns Ar c

and

.No \en( Ns Ar cc .

If the optional sign is specified,

the register is first incremented or decremented by the

.Ar stepsize

that was specified in the relevant

.Ic \&nr

request, and the changed value is interpolated.

.Ss \eo\(aq Ns Ar string Ns \(aq

Overstrike, writing all the characters contained in the

.Ar string

to the same output position.

In terminal and HTML output modes,

only the last one of the characters is visible.

.Ss \ep

Break the output line at the end of the current word.

.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq

Set number register; ignored by

.Xr mandoc 1 .

Line 1994 Change point size; ignored by

Line 2029 Change point size; ignored by

Alternative forms

.No \es Ns Oo +|- Oc Ns Ar n ,

.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,

.No \es Ns [ Oo +|- Oc Ns Ar number ] ,

.No \es Ns Bq Oo +|- Oc Ns Ar number ,

and

.No \es Ns Oo +|- Oc Ns [ Ar number Ns ]

.No \es Ns Oo +|- Oc Ns Bq Ar number

are also parsed and ignored.

.Ss \et

Horizontal tab; ignored by

Line 2004 Horizontal tab; ignored by

Line 2039 Horizontal tab; ignored by

.Ss \eu

Move up by half a line; ignored by

.Xr mandoc 1 .

.Ss \eV[ Ns Ar name ]

.Ss \eV Ns Bq Ar name

Interpolate an environment variable; ignored by

.Xr mandoc 1 .

For short names, there are variants

Line 2031 as device control function; ignored in nroff mode and

Line 2066 as device control function; ignored in nroff mode and

.Ss \ex\(aq Ns Ar number Ns \(aq

Extra line space function; ignored by

.Xr mandoc 1 .

.Ss \eY[ Ns Ar name ]

.Ss \eY Ns Bq Ar name

Output a string as a device control function; ignored in nroff mode and by

.Xr mandoc 1 .

For short names, there are variants

CVSweb