-.\" $Id: roff.7,v 1.15 2010/12/06 16:37:32 kristaps Exp $
+.\" $Id: roff.7,v 1.29 2011/05/24 15:22:14 kristaps Exp $
.\"
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" 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 6 2010 $
+.Dd $Mdocdate: May 24 2011 $
.Dt ROFF 7
.Os
.Sh NAME
.Nm roff
-.Nd roff language reference
+.Nd roff language reference for mandoc
.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
+language is a general purpose text formatting language.
+In particular, it serves as the basis for the
+.Xr mdoc 7
+and
+.Xr man 7
+manual formatting macro languages.
+This manual describes the subset of the
+.Nm
+language accepted by the
.Xr mandoc 1
-utility. It is a work in progress.
+utility.
.Pp
-An
-.Nm
-document follows simple rules: lines beginning with the control
-characters
-.Sq \.
+Input 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
+These define the document structure, change the processing state
+and manipulate the formatting.
+Some requests and macros also produce formatted output,
+while others do not.
+.Pp
+All other input lines provide free-form text to be printed;
+the formatting of free-form 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. All
-manuals must have
-.Ux
-line terminators.
-.Sh MACRO SYNTAX
-Requests and macros are arbitrary in length and begin with a control
-character,
-.Sq \.
+character, and, in certain circumstances, the tab character.
+To produce other characters in the output, use the escape sequences
+documented in the
+.Xr mandoc_char 7
+manual.
+.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.
-An arbitrary amount of whitespace may sit between the control character
-and the request or macro name.
-Thus, the following are equivalent:
+.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
-\&.if
-\&.\ \ \ \&if
+\&.ig end
+\&.ig end
+\&. ig end
.Ed
+.Sh MACRO SYNTAX
+Macros 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 .
+To be recognized as the beginning of a quoted argument, the opening
+quote character must be preceded by a space character.
+.Pp
+A quoted argument may contain whitespace, and pairs of double quote
+characters
+.Pq Sq Qq
+resolve to single double quote characters.
+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.
.Sh REQUEST REFERENCE
-This section is a canonical reference of all requests recognized by the
+The
.Xr mandoc 1
.Nm
-parser.
-The
+parser recognizes the following requests.
+Note that the
.Nm
-language defines many more requests and macros not implemented in
+language defines many more requests not implemented in
.Xr mandoc 1 .
.Ss \&ad
Set line adjustment mode.
.Xr mandoc 1 ,
as are its children.
.Ss \&de
-Define a user-defined
+Define a
.Nm
macro.
Its syntax can be either
.Nm
macro, but not as a high-level macro.
.Pp
-A user-defined macro can be invoked later using the syntax
+The 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.
+Regarding argument parsing, see
+.Sx MACRO SYNTAX
+above.
.Pp
-The line invoking the user-defined macro will be replaced
+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
+where
.Ar N
is a digit, by the
.Ar N Ns th Ar argument .
.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,
+Since macros and user-defined strings share a common string table,
defining a macro
.Ar name
clobbers the user-defined string
.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
+Define a
.Nm
macro, specifying the macro name indirectly.
-The syntax of this macro is the same as that of
+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 user-defined
+Define a
.Nm
macro that will be executed with
.Nm
.Xr mandoc 1
does not implement
.Nm
-compatibility mode at all, it handles this macro as an alias for
+compatibility mode at all, it handles this request as an alias for
.Sx \&de .
.Ss \&ds
Define a user-defined string.
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 user-defined macro
+clobbers the macro
.Ar name ,
and the
.Ar name
.Sx \&ie
calls)
then false is assumed.
-The syntax of this macro is similar to
+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.
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.
+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 \e .ig
+.D1 \&.if t .ig
.Pp
will discard the
.Sq \&.ig ,
which may lead to interesting results, but
.Pp
-.D1 \&.if t \e .if t \e{\e
+.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 macro has the following syntax:
-.Pp
-.Bd -literal -offset indent -compact
+This request has the following syntax:
+.Bd -literal -offset indent
\&.if COND \e{\e
BODY...
\&.\e}
.Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
\&.if COND \e{ BODY
BODY... \e}
.Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
\&.if COND \e{ BODY
BODY...
\&.\e}
.Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
\&.if COND \e
BODY
.Ed
.Pp
If the BODY section is begun by an escaped brace
.Sq \e{ ,
-scope continues until a closing-brace macro
+scope continues until a closing-brace escape sequence
.Sq \.\e} .
-If the BODY is not enclosed in braces, scope continues until the next
-macro or word.
+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 macros
+brace or not, then requests and macros
.Em must
begin with a control character.
It is generally more intuitive, in this case, to write
\&.\e}
.Ed
.Pp
-than having the macro follow as
+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 text subsequent a
-.Sq \&.\e}
-macro is discarded.
-Furthermore, if an explicit closing sequence
+Note that the
.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
+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}
-collapsing into a zero-width space.
+being considered an argument of the
+.Sq \&Fl
+macro.
.Ss \&ig
Ignore input.
Its syntax can be either
.Pp
In the first case, input is ignored until a
.Sq \&..
-macro is encountered on its own line.
+request is encountered on its own line.
In the second case, input is ignored until the specified
.Sq Pf . Ar end
macro is encountered.
.Ar ignored text ,
and arguments following it or the
.Sq \&..
-macro are discarded.
+request are discarded.
.Ss \&ne
Declare the need for the specified minimum vertical space
before the next trap or the bottom of the page.
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:
.It Cm nS
If set to a positive integer value, certain
.Xr mdoc 7
-macros will behave as if they were defined in the
+macros will behave in the same way as in the
.Em SYNOPSIS
section.
-Otherwise, this behaviour is unset (even if called within the
+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 invoking a new
+section itself.
+Note that starting a new
.Xr mdoc 7
-section will unset this value.
+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:
will be read and its contents processed as input in place of the
.Sq \&.so
request line.
-To avoid inadvertant inclusion of unrelated files,
+To avoid inadvertent inclusion of unrelated files,
.Xr mandoc 1
only accepts relative paths not containing the strings
.Qq ../
and
.Qq /.. .
+.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.
-This macro is intended to have one argument,
+This request 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.
+.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
-troff implementations, at this time limited to GNU troff
+.Nm
+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 .
+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
-request to
-.Sx \&nr
-is only compatible with OpenBSD's groff.
+register is only compatible with OpenBSD's groff-1.15.
.It
-Historic groff did not accept white-space buffering the custom END tag
-for the
+Historic groff did not accept white-space before a custom
+.Ar end
+macro for the
.Sx \&ig
-macro.
+request.
.It
The
.Sx \&if
and family would print funny white-spaces with historic groff when
-depending on next-line syntax.
+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 was written in PL/1 for the CTSS
+operating system by Jerome ("Jerry") E. Saltzer in 1961.
+It was first used as the main documentation tool by Multics since 1963.
+Robert ("Bob") H. Morris ported it to the GE-635 and called it
+.Nm ,
+Doug McIlroy rewrote it in BCPL in 1969,
+Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
+and Brian W. Kernighan rewrote it in C in 1975.
.Sh AUTHORS
.An -nosplit
This partial
git.ckatri.com / mandoc.git / blobdiff