1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
.\" $Id$
.\"
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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$
.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 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
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 macro name.
Thus, the following are equivalent:
.Bd -literal -offset indent
\&.if
\&.\ \ \ \&if
.Ed
.Sh REFERENCE
This section is a canonical reference of all macros, arranged
alphabetically.
.Ss \&if
Begins a conditional.
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 (TODO: document).
.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.
.Ss \&ig
Ignore input.
Accepts the following syntax:
.Pp
.Bd -literal -offset indent -compact
\&.ig
BODY...
\&..
.Ed
.Bd -literal -offset indent -compact
\&.ig END
BODY...
\&.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 a
.Sq \&.END
is encountered.
Text subsequent the
.Sq \&.END
or
.Sq \&..
is discarded.
.Pp
Do not use the escape
.Sq \e
anywhere in the definition of END.
It causes very strange behaviour.
Furthermore, if you redefine a
.Nm
macro, such as
.Pp
.D1 \&.ig if
.Pp
the subsequent invocation of
.Sx \&if
will first signify the end of comment, then be invoked as a macro.
This behaviour really shouldn't be counted upon.
.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
Historic groff did not accept white-space buffering the custom END tag
for the
.Sx \&ig
macro.
.El
.Sh AUTHORS
The
.Nm
reference was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
|
