mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-25 11:37:56 +00:00
e4d7d10517
It's not yet connected to the build.
990 lines
23 KiB
Groff
990 lines
23 KiB
Groff
.\" $Id: roff.7,v 1.37 2011/12/11 00:38:11 schwarze Exp $
|
|
.\"
|
|
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: December 11 2011 $
|
|
.Dt ROFF 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm roff
|
|
.Nd roff language reference for mandoc
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm roff
|
|
language is a general purpose text formatting language.
|
|
Since traditional implementations of the
|
|
.Xr mdoc 7
|
|
and
|
|
.Xr man 7
|
|
manual formatting languages are based on it,
|
|
many real-world manuals use small numbers of
|
|
.Nm
|
|
requests intermixed with their
|
|
.Xr mdoc 7
|
|
or
|
|
.Xr man 7
|
|
code.
|
|
To properly format such manuals, the
|
|
.Xr mandoc 1
|
|
utility supports a tiny subset of
|
|
.Nm
|
|
requests.
|
|
Only these requests supported by
|
|
.Xr mandoc 1
|
|
are documented in the present manual,
|
|
together with the basic language syntax shared by
|
|
.Nm ,
|
|
.Xr mdoc 7 ,
|
|
and
|
|
.Xr man 7 .
|
|
For complete
|
|
.Nm
|
|
manuals, consult the
|
|
.Sx SEE ALSO
|
|
section.
|
|
.Pp
|
|
Input lines beginning with the control character
|
|
.Sq \&.
|
|
are parsed for requests and macros.
|
|
Such lines are called
|
|
.Dq request lines
|
|
or
|
|
.Dq macro lines ,
|
|
respectively.
|
|
Requests change the processing state and manipulate the formatting;
|
|
some macros also define the document structure and produce formatted
|
|
output.
|
|
The single quote
|
|
.Pq Qq \(aq
|
|
is accepted as an alternative control character,
|
|
treated by
|
|
.Xr mandoc 1
|
|
just like
|
|
.Ql \&.
|
|
.Pp
|
|
Lines not beginning with control characters are called
|
|
.Dq text lines .
|
|
They provide free-form text to be printed; the formatting of the text
|
|
depends on the respective processing context.
|
|
.Sh LANGUAGE SYNTAX
|
|
.Nm
|
|
documents may contain only graphable 7-bit ASCII characters, the space
|
|
character, and, in certain circumstances, the tab character.
|
|
The back-space character
|
|
.Sq \e
|
|
indicates the start of an escape sequence for
|
|
.Sx Comments ,
|
|
.Sx Special Characters ,
|
|
.Sx Predefined Strings ,
|
|
and
|
|
user-defined strings defined using the
|
|
.Sx ds
|
|
request.
|
|
.Ss Comments
|
|
Text following an escaped double-quote
|
|
.Sq \e\(dq ,
|
|
whether in a request, macro, or text line, is ignored to the end of the line.
|
|
A request line beginning with a control character and comment escape
|
|
.Sq \&.\e\(dq
|
|
is also ignored.
|
|
Furthermore, request lines with only a control character and optional
|
|
trailing whitespace are stripped from input.
|
|
.Pp
|
|
Examples:
|
|
.Bd -literal -offset indent -compact
|
|
\&.\e\(dq This is a comment line.
|
|
\&.\e\(dq The next line is ignored:
|
|
\&.
|
|
\&.Sh EXAMPLES \e\(dq This is a comment, too.
|
|
\&example text \e\(dq And so is this.
|
|
.Ed
|
|
.Ss Special Characters
|
|
Special characters are used to encode special glyphs and are rendered
|
|
differently across output media.
|
|
They may occur in request, macro, and text 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.
|
|
.Pp
|
|
Examples:
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It Li \e(em
|
|
Two-letter em dash escape.
|
|
.It Li \ee
|
|
One-letter backslash escape.
|
|
.El
|
|
.Pp
|
|
See
|
|
.Xr mandoc_char 7
|
|
for a complete list.
|
|
.Ss Text Decoration
|
|
Terms may be text-decorated using the
|
|
.Sq \ef
|
|
escape followed by an indicator: B (bold), I (italic), R (regular), or P
|
|
(revert to previous mode).
|
|
A numerical representation 3, 2, or 1 (bold, italic, and regular,
|
|
respectively) may be used instead.
|
|
The indicator or numerical representative may be preceded by C
|
|
(constant-width), which is ignored.
|
|
.Pp
|
|
Examples:
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It Li \efBbold\efR
|
|
Write in bold, then switch to regular font mode.
|
|
.It Li \efIitalic\efP
|
|
Write in italic, then return to previous font mode.
|
|
.El
|
|
.Pp
|
|
Text decoration is
|
|
.Em not
|
|
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.
|
|
In request and macro lines, whitespace delimits arguments and is discarded.
|
|
.Pp
|
|
Unescaped trailing spaces are stripped from text line input unless in a
|
|
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
|
|
input line, it may be forced by
|
|
.Sq \e\ \e& .
|
|
.Pp
|
|
Literal space characters can be produced in the output
|
|
using escape sequences.
|
|
In macro lines, they can also be included in arguments using quotation; see
|
|
.Sx MACRO SYNTAX
|
|
for details.
|
|
.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 Scaling Widths
|
|
Many requests and macros support scaled widths for their arguments.
|
|
The syntax for a scaled width is
|
|
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
|
|
where a decimal must be preceded or followed by at least one digit.
|
|
Negative numbers, while accepted, are truncated to zero.
|
|
.Pp
|
|
The following scaling units are accepted:
|
|
.Pp
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It c
|
|
centimetre
|
|
.It i
|
|
inch
|
|
.It P
|
|
pica (~1/6 inch)
|
|
.It p
|
|
point (~1/72 inch)
|
|
.It f
|
|
synonym for
|
|
.Sq u
|
|
.It v
|
|
default vertical span
|
|
.It m
|
|
width of rendered
|
|
.Sq m
|
|
.Pq em
|
|
character
|
|
.It n
|
|
width of rendered
|
|
.Sq n
|
|
.Pq en
|
|
character
|
|
.It u
|
|
default horizontal span
|
|
.It M
|
|
mini-em (~1/100 em)
|
|
.El
|
|
.Pp
|
|
Using anything other than
|
|
.Sq m ,
|
|
.Sq n ,
|
|
.Sq u ,
|
|
or
|
|
.Sq v
|
|
is necessarily non-portable across output media.
|
|
See
|
|
.Sx COMPATIBILITY .
|
|
.Pp
|
|
If a scaling unit is not provided, the numerical value is interpreted
|
|
under the default rules of
|
|
.Sq v
|
|
for vertical spaces and
|
|
.Sq u
|
|
for horizontal ones.
|
|
.Pp
|
|
Examples:
|
|
.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
|
|
.It Li \&.Bl -tag -width 2i
|
|
two-inch tagged list indentation in
|
|
.Xr mdoc 7
|
|
.It Li \&.HP 2i
|
|
two-inch tagged list indentation in
|
|
.Xr man 7
|
|
.It Li \&.sp 2v
|
|
two vertical spaces
|
|
.El
|
|
.Ss Sentence Spacing
|
|
Each sentence should terminate at the end of an input line.
|
|
By doing this, a formatter will be able to apply the proper amount of
|
|
spacing after the end of sentence (unescaped) period, exclamation mark,
|
|
or question mark followed by zero or more non-sentence closing
|
|
delimiters
|
|
.Po
|
|
.Sq \&) ,
|
|
.Sq \&] ,
|
|
.Sq \&' ,
|
|
.Sq \&"
|
|
.Pc .
|
|
.Pp
|
|
The proper spacing is also intelligently preserved if a sentence ends at
|
|
the boundary of a macro line.
|
|
.Pp
|
|
Examples:
|
|
.Bd -literal -offset indent -compact
|
|
Do not end sentences mid-line like this. Instead,
|
|
end a sentence like this.
|
|
A macro would end like this:
|
|
\&.Xr mandoc 1 \&.
|
|
.Ed
|
|
.Sh REQUEST SYNTAX
|
|
A request or macro line consists of:
|
|
.Pp
|
|
.Bl -enum -compact
|
|
.It
|
|
the control character
|
|
.Sq \&.
|
|
or
|
|
.Sq \(aq
|
|
at the beginning of the line,
|
|
.It
|
|
optionally an arbitrary amount of whitespace,
|
|
.It
|
|
the name of the request or the macro, which is one word of arbitrary
|
|
length, terminated by whitespace,
|
|
.It
|
|
and zero or more arguments delimited by whitespace.
|
|
.El
|
|
.Pp
|
|
Thus, the following request lines are all equivalent:
|
|
.Bd -literal -offset indent
|
|
\&.ig end
|
|
\&.ig end
|
|
\&. ig end
|
|
.Ed
|
|
.Sh MACRO SYNTAX
|
|
Macros are provided by the
|
|
.Xr mdoc 7
|
|
and
|
|
.Xr man 7
|
|
languages and can be defined by the
|
|
.Sx \&de
|
|
request.
|
|
When called, they follow the same syntax as requests, except that
|
|
macro arguments may optionally be quoted by enclosing them
|
|
in double quote characters
|
|
.Pq Sq \(dq .
|
|
Quoted text, even if it contains whitespace or would cause
|
|
a macro invocation when unquoted, is always considered literal text.
|
|
Inside quoted text, pairs of double quote characters
|
|
.Pq Sq Qq
|
|
resolve to single double quote characters.
|
|
.Pp
|
|
To be recognised as the beginning of a quoted argument, the opening
|
|
quote character must be preceded by a space character.
|
|
A quoted argument extends to the next double quote character that is not
|
|
part of a pair, or to the end of the input line, whichever comes earlier.
|
|
Leaving out the terminating double quote character at the end of the line
|
|
is discouraged.
|
|
For clarity, if more arguments follow on the same input line,
|
|
it is recommended to follow the terminating double quote character
|
|
by a space character; in case the next character after the terminating
|
|
double quote character is anything else, it is regarded as the beginning
|
|
of the next, unquoted argument.
|
|
.Pp
|
|
Both in quoted and unquoted arguments, pairs of backslashes
|
|
.Pq Sq \e\e
|
|
resolve to single backslashes.
|
|
In unquoted arguments, space characters can alternatively be included
|
|
by preceding them with a backslash
|
|
.Pq Sq \e\~ ,
|
|
but quoting is usually better for clarity.
|
|
.Pp
|
|
Examples:
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It Li .Fn strlen \(dqconst char *s\(dq
|
|
Group arguments
|
|
.Qq const char *s
|
|
into one function argument.
|
|
If unspecified,
|
|
.Qq const ,
|
|
.Qq char ,
|
|
and
|
|
.Qq *s
|
|
would be considered separate arguments.
|
|
.It Li .Op \(dqFl a\(dq
|
|
Consider
|
|
.Qq \&Fl a
|
|
as literal text instead of a flag macro.
|
|
.El
|
|
.Sh REQUEST REFERENCE
|
|
The
|
|
.Xr mandoc 1
|
|
.Nm
|
|
parser recognises the following requests.
|
|
Note that the
|
|
.Nm
|
|
language defines many more requests not implemented in
|
|
.Xr mandoc 1 .
|
|
.Ss \&ad
|
|
Set line adjustment mode.
|
|
This line-scoped request is intended to have one argument to select
|
|
normal, left, right, or centre adjustment for subsequent text.
|
|
Currently, it is ignored including its arguments,
|
|
and the number of arguments is not checked.
|
|
.Ss \&am
|
|
Append to a macro definition.
|
|
The syntax of this request is the same as that of
|
|
.Sx \&de .
|
|
It is currently ignored by
|
|
.Xr mandoc 1 ,
|
|
as are its children.
|
|
.Ss \&ami
|
|
Append to a macro definition, specifying the macro name indirectly.
|
|
The syntax of this request is the same as that of
|
|
.Sx \&dei .
|
|
It is currently ignored by
|
|
.Xr mandoc 1 ,
|
|
as are its children.
|
|
.Ss \&am1
|
|
Append to a macro definition, switching roff compatibility mode off
|
|
during macro execution.
|
|
The syntax of this request is the same as that of
|
|
.Sx \&de1 .
|
|
It is currently ignored by
|
|
.Xr mandoc 1 ,
|
|
as are its children.
|
|
.Ss \&de
|
|
Define a
|
|
.Nm
|
|
macro.
|
|
Its syntax can be either
|
|
.Bd -literal -offset indent
|
|
.Pf . Cm \&de Ar name
|
|
.Ar macro definition
|
|
\&..
|
|
.Ed
|
|
.Pp
|
|
or
|
|
.Bd -literal -offset indent
|
|
.Pf . Cm \&de Ar name Ar end
|
|
.Ar macro definition
|
|
.Pf . Ar end
|
|
.Ed
|
|
.Pp
|
|
Both forms define or redefine the macro
|
|
.Ar name
|
|
to represent the
|
|
.Ar macro definition ,
|
|
which may consist of one or more input lines, including the newline
|
|
characters terminating each line, optionally containing calls to
|
|
.Nm
|
|
requests,
|
|
.Nm
|
|
macros or high-level macros like
|
|
.Xr man 7
|
|
or
|
|
.Xr mdoc 7
|
|
macros, whichever applies to the document in question.
|
|
.Pp
|
|
Specifying a custom
|
|
.Ar end
|
|
macro works in the same way as for
|
|
.Sx \&ig ;
|
|
namely, the call to
|
|
.Sq Pf . Ar end
|
|
first ends the
|
|
.Ar macro definition ,
|
|
and after that, it is also evaluated as a
|
|
.Nm
|
|
request or
|
|
.Nm
|
|
macro, but not as a high-level macro.
|
|
.Pp
|
|
The macro can be invoked later using the syntax
|
|
.Pp
|
|
.D1 Pf . Ar name Op Ar argument Op Ar argument ...
|
|
.Pp
|
|
Regarding argument parsing, see
|
|
.Sx MACRO SYNTAX
|
|
above.
|
|
.Pp
|
|
The line invoking the macro will be replaced
|
|
in the input stream by the
|
|
.Ar macro definition ,
|
|
replacing all occurrences of
|
|
.No \e\e$ Ns Ar N ,
|
|
where
|
|
.Ar N
|
|
is a digit, by the
|
|
.Ar N Ns th Ar argument .
|
|
For example,
|
|
.Bd -literal -offset indent
|
|
\&.de ZN
|
|
\efI\e^\e\e$1\e^\efP\e\e$2
|
|
\&..
|
|
\&.ZN XtFree .
|
|
.Ed
|
|
.Pp
|
|
produces
|
|
.Pp
|
|
.D1 \efI\e^XtFree\e^\efP.
|
|
.Pp
|
|
in the input stream, and thus in the output: \fI\^XtFree\^\fP.
|
|
.Pp
|
|
Since macros and user-defined strings share a common string table,
|
|
defining a macro
|
|
.Ar name
|
|
clobbers the user-defined string
|
|
.Ar name ,
|
|
and the
|
|
.Ar macro definition
|
|
can also be printed using the
|
|
.Sq \e*
|
|
string interpolation syntax described below
|
|
.Sx ds ,
|
|
but this is rarely useful because every macro definition contains at least
|
|
one explicit newline character.
|
|
.Pp
|
|
In order to prevent endless recursion, both groff and
|
|
.Xr mandoc 1
|
|
limit the stack depth for expanding macros and strings
|
|
to a large, but finite number.
|
|
Do not rely on the exact value of this limit.
|
|
.Ss \&dei
|
|
Define a
|
|
.Nm
|
|
macro, specifying the macro name indirectly.
|
|
The syntax of this request is the same as that of
|
|
.Sx \&de .
|
|
It is currently ignored by
|
|
.Xr mandoc 1 ,
|
|
as are its children.
|
|
.Ss \&de1
|
|
Define a
|
|
.Nm
|
|
macro that will be executed with
|
|
.Nm
|
|
compatibility mode switched off during macro execution.
|
|
This is a GNU extension not available in traditional
|
|
.Nm
|
|
implementations and not even in older versions of groff.
|
|
Since
|
|
.Xr mandoc 1
|
|
does not implement
|
|
.Nm
|
|
compatibility mode at all, it handles this request as an alias for
|
|
.Sx \&de .
|
|
.Ss \&ds
|
|
Define a user-defined string.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
|
|
.Pp
|
|
The
|
|
.Ar name
|
|
and
|
|
.Ar string
|
|
arguments are space-separated.
|
|
If the
|
|
.Ar string
|
|
begins with a double-quote character, that character will not be part
|
|
of the string.
|
|
All remaining characters on the input line form the
|
|
.Ar string ,
|
|
including whitespace and double-quote characters, even trailing ones.
|
|
.Pp
|
|
The
|
|
.Ar string
|
|
can be interpolated into subsequent text by using
|
|
.No \e* Ns Bq Ar name
|
|
for a
|
|
.Ar name
|
|
of arbitrary length, or \e*(NN or \e*N if the length of
|
|
.Ar name
|
|
is two or one characters, respectively.
|
|
Interpolation can be prevented by escaping the leading backslash;
|
|
that is, an asterisk preceded by an even number of backslashes
|
|
does not trigger string interpolation.
|
|
.Pp
|
|
Since user-defined strings and macros share a common string table,
|
|
defining a string
|
|
.Ar name
|
|
clobbers the macro
|
|
.Ar name ,
|
|
and the
|
|
.Ar name
|
|
used for defining a string can also be invoked as a macro,
|
|
in which case the following input line will be appended to the
|
|
.Ar string ,
|
|
forming a new input line passed to the
|
|
.Nm
|
|
parser.
|
|
For example,
|
|
.Bd -literal -offset indent
|
|
\&.ds badidea .S
|
|
\&.badidea
|
|
H SYNOPSIS
|
|
.Ed
|
|
.Pp
|
|
invokes the
|
|
.Cm SH
|
|
macro when used in a
|
|
.Xr man 7
|
|
document.
|
|
Such abuse is of course strongly discouraged.
|
|
.Ss \&el
|
|
The
|
|
.Qq else
|
|
half of an if/else conditional.
|
|
Pops a result off the stack of conditional evaluations pushed by
|
|
.Sx \&ie
|
|
and uses it as its conditional.
|
|
If no stack entries are present (e.g., due to no prior
|
|
.Sx \&ie
|
|
calls)
|
|
then false is assumed.
|
|
The syntax of this request is similar to
|
|
.Sx \&if
|
|
except that the conditional is missing.
|
|
.Ss \&EN
|
|
End an equation block.
|
|
See
|
|
.Sx \&EQ .
|
|
.Ss \&EQ
|
|
Begin an equation block.
|
|
See
|
|
.Xr eqn 7
|
|
for a description of the equation language.
|
|
.Ss \&hy
|
|
Set automatic hyphenation mode.
|
|
This line-scoped request is currently ignored.
|
|
.Ss \&ie
|
|
The
|
|
.Qq if
|
|
half of an if/else conditional.
|
|
The result of the conditional is pushed into a stack used by subsequent
|
|
invocations of
|
|
.Sx \&el ,
|
|
which may be separated by any intervening input (or not exist at all).
|
|
Its syntax is equivalent to
|
|
.Sx \&if .
|
|
.Ss \&if
|
|
Begins a conditional.
|
|
Right now, the conditional evaluates to true
|
|
if and only if it starts with the letter
|
|
.Sy n ,
|
|
indicating processing in nroff style as opposed to troff style.
|
|
If a conditional is false, its children are not processed, but are
|
|
syntactically interpreted to preserve the integrity of the input
|
|
document.
|
|
Thus,
|
|
.Pp
|
|
.D1 \&.if t .ig
|
|
.Pp
|
|
will discard the
|
|
.Sq \&.ig ,
|
|
which may lead to interesting results, but
|
|
.Pp
|
|
.D1 \&.if t .if t \e{\e
|
|
.Pp
|
|
will continue to syntactically interpret to the block close of the final
|
|
conditional.
|
|
Sub-conditionals, in this case, obviously inherit the truth value of
|
|
the parent.
|
|
This request has the following syntax:
|
|
.Bd -literal -offset indent
|
|
\&.if COND \e{\e
|
|
BODY...
|
|
\&.\e}
|
|
.Ed
|
|
.Bd -literal -offset indent
|
|
\&.if COND \e{ BODY
|
|
BODY... \e}
|
|
.Ed
|
|
.Bd -literal -offset indent
|
|
\&.if COND \e{ BODY
|
|
BODY...
|
|
\&.\e}
|
|
.Ed
|
|
.Bd -literal -offset indent
|
|
\&.if COND \e
|
|
BODY
|
|
.Ed
|
|
.Pp
|
|
COND is a conditional statement.
|
|
roff allows for complicated conditionals; mandoc is much simpler.
|
|
At this time, mandoc supports only
|
|
.Sq n ,
|
|
evaluating to true;
|
|
and
|
|
.Sq t ,
|
|
.Sq e ,
|
|
and
|
|
.Sq o ,
|
|
evaluating to false.
|
|
All other invocations are read up to the next end of line or space and
|
|
evaluate as false.
|
|
.Pp
|
|
If the BODY section is begun by an escaped brace
|
|
.Sq \e{ ,
|
|
scope continues until a closing-brace escape sequence
|
|
.Sq \.\e} .
|
|
If the BODY is not enclosed in braces, scope continues until
|
|
the end of the line.
|
|
If the COND is followed by a BODY on the same line, whether after a
|
|
brace or not, then requests and macros
|
|
.Em must
|
|
begin with a control character.
|
|
It is generally more intuitive, in this case, to write
|
|
.Bd -literal -offset indent
|
|
\&.if COND \e{\e
|
|
\&.foo
|
|
bar
|
|
\&.\e}
|
|
.Ed
|
|
.Pp
|
|
than having the request or macro follow as
|
|
.Pp
|
|
.D1 \&.if COND \e{ .foo
|
|
.Pp
|
|
The scope of a conditional is always parsed, but only executed if the
|
|
conditional evaluates to true.
|
|
.Pp
|
|
Note that the
|
|
.Sq \e}
|
|
is converted into a zero-width escape sequence if not passed as a
|
|
standalone macro
|
|
.Sq \&.\e} .
|
|
For example,
|
|
.Pp
|
|
.D1 \&.Fl a \e} b
|
|
.Pp
|
|
will result in
|
|
.Sq \e}
|
|
being considered an argument of the
|
|
.Sq \&Fl
|
|
macro.
|
|
.Ss \&ig
|
|
Ignore input.
|
|
Its syntax can be either
|
|
.Bd -literal -offset indent
|
|
.Pf . Cm \&ig
|
|
.Ar ignored text
|
|
\&..
|
|
.Ed
|
|
.Pp
|
|
or
|
|
.Bd -literal -offset indent
|
|
.Pf . Cm \&ig Ar end
|
|
.Ar ignored text
|
|
.Pf . Ar end
|
|
.Ed
|
|
.Pp
|
|
In the first case, input is ignored until a
|
|
.Sq \&..
|
|
request is encountered on its own line.
|
|
In the second case, input is ignored until the specified
|
|
.Sq Pf . Ar end
|
|
macro is encountered.
|
|
Do not use the escape character
|
|
.Sq \e
|
|
anywhere in the definition of
|
|
.Ar end ;
|
|
it would cause very strange behaviour.
|
|
.Pp
|
|
When the
|
|
.Ar end
|
|
macro is a roff request or a roff macro, like in
|
|
.Pp
|
|
.D1 \&.ig if
|
|
.Pp
|
|
the subsequent invocation of
|
|
.Sx \&if
|
|
will first terminate the
|
|
.Ar ignored text ,
|
|
then be invoked as usual.
|
|
Otherwise, it only terminates the
|
|
.Ar ignored text ,
|
|
and arguments following it or the
|
|
.Sq \&..
|
|
request are discarded.
|
|
.Ss \&ne
|
|
Declare the need for the specified minimum vertical space
|
|
before the next trap or the bottom of the page.
|
|
This line-scoped request is currently ignored.
|
|
.Ss \&nh
|
|
Turn off automatic hyphenation mode.
|
|
This line-scoped request is currently ignored.
|
|
.Ss \&rm
|
|
Remove a request, macro or string.
|
|
This request is intended to have one argument,
|
|
the name of the request, macro or string to be undefined.
|
|
Currently, it is ignored including its arguments,
|
|
and the number of arguments is not checked.
|
|
.Ss \&nr
|
|
Define a register.
|
|
A register is an arbitrary string value that defines some sort of state,
|
|
which influences parsing and/or formatting.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 Pf \. Cm \&nr Ar name Ar value
|
|
.Pp
|
|
The
|
|
.Ar value
|
|
may, at the moment, only be an integer.
|
|
So far, only the following register
|
|
.Ar name
|
|
is recognised:
|
|
.Bl -tag -width Ds
|
|
.It Cm nS
|
|
If set to a positive integer value, certain
|
|
.Xr mdoc 7
|
|
macros will behave in the same way as in the
|
|
.Em SYNOPSIS
|
|
section.
|
|
If set to 0, these macros will behave in the same way as outside the
|
|
.Em SYNOPSIS
|
|
section, even when called within the
|
|
.Em SYNOPSIS
|
|
section itself.
|
|
Note that starting a new
|
|
.Xr mdoc 7
|
|
section with the
|
|
.Cm \&Sh
|
|
macro will reset this register.
|
|
.El
|
|
.Ss \&ns
|
|
Turn on no-space mode.
|
|
This line-scoped request is intended to take no arguments.
|
|
Currently, it is ignored including its arguments,
|
|
and the number of arguments is not checked.
|
|
.Ss \&ps
|
|
Change point size.
|
|
This line-scoped request is intended to take one numerical argument.
|
|
Currently, it is ignored including its arguments,
|
|
and the number of arguments is not checked.
|
|
.Ss \&so
|
|
Include a source file.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 Pf \. Cm \&so Ar file
|
|
.Pp
|
|
The
|
|
.Ar file
|
|
will be read and its contents processed as input in place of the
|
|
.Sq \&.so
|
|
request line.
|
|
To avoid inadvertent inclusion of unrelated files,
|
|
.Xr mandoc 1
|
|
only accepts relative paths not containing the strings
|
|
.Qq ../
|
|
and
|
|
.Qq /.. .
|
|
.Pp
|
|
This request requires
|
|
.Xr man 1
|
|
to change to the right directory before calling
|
|
.Xr mandoc 1 ,
|
|
per convention to the root of the manual tree.
|
|
Typical usage looks like:
|
|
.Pp
|
|
.Dl \&.so man3/Xcursor.3
|
|
.Pp
|
|
As the whole concept is rather fragile, the use of
|
|
.Sx \&so
|
|
is discouraged.
|
|
Use
|
|
.Xr ln 1
|
|
instead.
|
|
.Ss \&ta
|
|
Set tab stops.
|
|
This line-scoped request can take an arbitrary number of arguments.
|
|
Currently, it is ignored including its arguments.
|
|
.Ss \&tr
|
|
Output character translation.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 Pf \. Cm \&tr Ar [ab]+
|
|
.Pp
|
|
Pairs of
|
|
.Ar ab
|
|
characters are replaced
|
|
.Ar ( a
|
|
for
|
|
.Ar b ) .
|
|
Replacement (or origin) characters may also be character escapes; thus,
|
|
.Pp
|
|
.Dl tr \e(xx\e(yy
|
|
.Pp
|
|
replaces all invocations of \e(xx with \e(yy.
|
|
.Ss \&T&
|
|
Re-start a table layout, retaining the options of the prior table
|
|
invocation.
|
|
See
|
|
.Sx \&TS .
|
|
.Ss \&TE
|
|
End a table context.
|
|
See
|
|
.Sx \&TS .
|
|
.Ss \&TS
|
|
Begin a table, which formats input in aligned rows and columns.
|
|
See
|
|
.Xr tbl 7
|
|
for a description of the tbl language.
|
|
.Sh COMPATIBILITY
|
|
This section documents compatibility between mandoc and other other
|
|
.Nm
|
|
implementations, at this time limited to GNU troff
|
|
.Pq Qq groff .
|
|
The term
|
|
.Qq historic groff
|
|
refers to groff version 1.15.
|
|
.Pp
|
|
.Bl -dash -compact
|
|
.It
|
|
In mandoc, the
|
|
.Sx \&EQ ,
|
|
.Sx \&TE ,
|
|
.Sx \&TS ,
|
|
and
|
|
.Sx \&T& ,
|
|
macros are considered regular macros.
|
|
In all other
|
|
.Nm
|
|
implementations, these are special macros that must be specified without
|
|
spacing between the control character (which must be a period) and the
|
|
macro name.
|
|
.It
|
|
The
|
|
.Cm nS
|
|
register is only compatible with OpenBSD's groff-1.15.
|
|
.It
|
|
Historic groff did not accept white-space before a custom
|
|
.Ar end
|
|
macro for the
|
|
.Sx \&ig
|
|
request.
|
|
.It
|
|
The
|
|
.Sx \&if
|
|
and family would print funny white-spaces with historic groff when
|
|
using the next-line syntax.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr mandoc 1 ,
|
|
.Xr eqn 7 ,
|
|
.Xr man 7 ,
|
|
.Xr mandoc_char 7 ,
|
|
.Xr mdoc 7 ,
|
|
.Xr tbl 7
|
|
.Rs
|
|
.%A Joseph F. Ossanna
|
|
.%A Brian W. Kernighan
|
|
.%I AT&T Bell Laboratories
|
|
.%T Troff User's Manual
|
|
.%R Computing Science Technical Report
|
|
.%N 54
|
|
.%C Murray Hill, New Jersey
|
|
.%D 1976 and 1992
|
|
.%U http://www.kohala.com/start/troff/cstr54.ps
|
|
.Re
|
|
.Rs
|
|
.%A Joseph F. Ossanna
|
|
.%A Brian W. Kernighan
|
|
.%A Gunnar Ritter
|
|
.%T Heirloom Documentation Tools Nroff/Troff User's Manual
|
|
.%D September 17, 2007
|
|
.%U http://heirloom.sourceforge.net/doctools/troff.pdf
|
|
.Re
|
|
.Sh HISTORY
|
|
The RUNOFF typesetting system, whose input forms the basis for
|
|
.Nm ,
|
|
was written in MAD and FAP for the CTSS operating system by Jerome E.
|
|
Saltzer in 1964.
|
|
Doug McIlroy rewrote it in BCPL in 1969, renaming it
|
|
.Nm .
|
|
Dennis M. Ritchie rewrote McIlroy's
|
|
.Nm
|
|
in PDP-11 assembly for
|
|
.At v1 ,
|
|
Joseph F. Ossanna improved roff and renamed it nroff
|
|
for
|
|
.At v2 ,
|
|
then ported nroff to C as troff, which Brian W. Kernighan released with
|
|
.At v7 .
|
|
In 1989, James Clarke re-implemented troff in C++, naming it groff.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
This
|
|
.Nm
|
|
reference was written by
|
|
.An Kristaps Dzonsons ,
|
|
.Mt kristaps@bsd.lv ;
|
|
and
|
|
.An Ingo Schwarze ,
|
|
.Mt schwarze@openbsd.org .
|