.\"	$Id: roff.7,v 1.16 2010/12/10 20:58:56 schwarze Exp $
.\"
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 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 10 2010 $
.Dt ROFF 7
.Os
.Sh NAME
.Nm roff
.Nd roff language reference
.Sh DESCRIPTION
The
.Nm roff
language is a general-purpose text-formatting language.  The purpose of
this document is to consistently describe those language constructs
accepted by the
.Xr mandoc 1
utility.  It is a work in progress.
.Pp
An
.Nm
document follows simple rules:  lines beginning with the control
characters
.Sq \.
or
.Sq \(aq
are parsed for requests and macros.
Other lines are interpreted within the scope of
prior macros:
.Bd -literal -offset indent
\&.xx Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
.Sh LANGUAGE SYNTAX
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character.  All
manuals must have
.Ux
line terminators.
.Sh MACRO SYNTAX
Requests and macros are arbitrary in length and begin with a control
character,
.Sq \.
or
.Sq \(aq ,
at the beginning of the line.
An arbitrary amount of whitespace may sit between the control character
and the request or macro name.
Thus, the following are equivalent:
.Bd -literal -offset indent
\&.if
\&.\ \ \ \&if
.Ed
.Sh REQUEST REFERENCE
This section is a canonical reference of all requests recognized by the
.Xr mandoc 1
.Nm
parser.
The
.Nm
language defines many more requests and macros 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 center 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 user-defined
.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
A user-defined macro can be invoked later using the syntax
.Pp
.D1 Pf . Ar name Op Ar argument Op Ar argument ...
.Pp
Arguments are separated by blank characters and can be quoted
using double-quotes
.Pq Sq \(dq
to allow inclusion of blank characters into arguments.
To include the double-quote character into a quoted argument,
escape it from ending the argument by doubling it.
.Pp
The line invoking the user-defined 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 user-defined macros and 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 user-defined
.Nm
macro, specifying the macro name indirectly.
The syntax of this macro is the same as that of
.Sx \&de .
It is currently ignored by
.Xr mandoc 1 ,
as are its children.
.Ss \&de1
Define a user-defined
.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 macro 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.
.Pp
Since user-defined strings and macros share a common string table,
defining a string
.Ar name
clobbers the user-defined 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 macro is similar to
.Sx \&if
except that the conditional is missing.
.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
.Xr nroff 1
style as opposed to
.Xr troff 1
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 \e .ig
.Pp
will discard the
.Sq \&.ig ,
which may lead to interesting results, but
.Pp
.D1 \&.if t \e .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 macro has the following syntax:
.Pp
.Bd -literal -offset indent -compact
\&.if COND \e{\e
BODY...
\&.\e}
.Ed
.Bd -literal -offset indent -compact
\&.if COND \e{ BODY
BODY... \e}
.Ed
.Bd -literal -offset indent -compact
\&.if COND \e{ BODY
BODY...
\&.\e}
.Ed
.Bd -literal -offset indent -compact
\&.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 macro
.Sq \.\e} .
If the BODY is not enclosed in braces, scope continues until the next
macro or word.
If the COND is followed by a BODY on the same line, whether after a
brace or not, then 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 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 text subsequent a
.Sq \&.\e}
macro is discarded.
Furthermore, if an explicit closing sequence
.Sq \e}
is specified in a free-form line, the entire line is accepted within the
scope of the prior macro, not only the text preceding the close, with the
.Sq \e}
collapsing into a zero-width space.
.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 \&..
macro 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 \&..
macro 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.
The
.Ar name
is defined up to the next whitespace.
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 as if they were defined in the
.Em SYNOPSIS
section.
Otherwise, this behaviour is unset (even if called within the
.Em SYNOPSIS
section itself).
Note that invoking a new
.Xr mdoc 7
section will unset this value.
.El
.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 inadvertant inclusion of unrelated files,
.Xr mandoc 1
only accepts relative paths not containing the strings
.Qq ../
and
.Qq /.. .
.Ss \&tr
Output character translation.
This macro is intended to have one argument,
consisting of an even number of characters.
Currently, it is ignored including its arguments,
and the number of arguments is not checked.
.Sh COMPATIBILITY
This section documents compatibility between mandoc and other other
troff implementations, at this time limited to GNU troff
.Pq Qq groff .
The term
.Qq historic groff
refers to groff versions before the
.Pa doc.tmac
file re-write
.Pq somewhere between 1.15 and 1.19 .
.Pp
.Bl -dash -compact
.It
The
.Cm nS
request to
.Sx \&nr
is only compatible with OpenBSD's groff.
.It
Historic groff did not accept white-space buffering the custom END tag
for the
.Sx \&ig
macro.
.It
The
.Sx \&if
and family would print funny white-spaces with historic groff when
depending on next-line syntax.
.El
.Sh AUTHORS
.An -nosplit
This partial
.Nm
reference was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv
and
.An Ingo Schwarze Aq schwarze@openbsd.org .