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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- This manual documents GNU troff version 1.23.0.
Copyright 1994-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<title>Compatibility Mode (The GNU Troff Manual)</title>
<meta name="description" content="Compatibility Mode (The GNU Troff Manual)">
<meta name="keywords" content="Compatibility Mode (The GNU Troff Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Request-Index.html" rel="index" title="Request Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Implementation-Differences.html" rel="up" title="Implementation Differences">
<link href="Safer-Mode.html" rel="next" title="Safer Mode">
<link href="Other-Differences.html" rel="prev" title="Other Differences">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
</head>
<body lang="en">
<div class="subsection-level-extent" id="Compatibility-Mode">
<div class="nav-panel">
<p>
Next: <a href="Safer-Mode.html" accesskey="n" rel="next">Safer Mode</a>, Previous: <a href="Other-Differences.html" accesskey="p" rel="prev">Other Differences</a>, Up: <a href="Implementation-Differences.html" accesskey="u" rel="up">Implementation Differences</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Compatibility-Mode-1">5.38.2 Compatibility Mode</h4>
<a class="index-entry-id" id="index-compatibility-mode-1"></a>
<a class="index-entry-id" id="index-mode_002c-compatibility"></a>
<a class="index-entry-id" id="index-long-names"></a>
<a class="index-entry-id" id="index-names_002c-long"></a>
<a class="index-entry-id" id="index-_005c_002a_002c-incompatibilities-with-AT_0026T-troff"></a>
<a class="index-entry-id" id="index-_005cn_002c-incompatibilities-with-AT_0026T-troff"></a>
<p>Long identifier names may be GNU <code class="code">troff</code>’s most obvious innovation.
<abbr class="acronym">AT&T</abbr> <code class="code">troff</code> interprets ‘<samp class="samp">.dsabcd</samp>’ as defining a
string ‘<samp class="samp">ab</samp>’ with contents ‘<samp class="samp">cd</samp>’. Normally, GNU <code class="code">troff</code>
interprets this as a call of a macro named <code class="code">dsabcd</code>.
<abbr class="acronym">AT&T</abbr> <code class="code">troff</code> also interprets ‘<samp class="samp">\*[</samp>’ and ‘<samp class="samp">\n[</samp>’ as
an interpolation of a string or register, respectively, named ‘<samp class="samp">[</samp>’.
In GNU <code class="code">troff</code>, however, the ‘<samp class="samp">[</samp>’ is normally interpreted as
delimiting a long name. In compatibility mode, GNU <code class="code">troff</code>
interprets names in the traditional way; they thus can be two characters
long at most.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ecp"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.cp</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">n</i></span>]</var><a class="copiable-link" href='#index-_002ecp'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-cp"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005cn_005b_002eC_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.C]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002eC_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002eC"></a>
<p>If <var class="var">n</var> is missing or non-zero, turn on compatibility mode;
otherwise, turn it off.
</p>
<p>The read-only register <code class="code">.C</code> is 1 if compatibility mode is on,
0 otherwise.
</p>
<p>Compatibility mode can be also turned on with the <samp class="option">-C</samp>
command-line option.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002edo"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.do</code></strong> <var class="def-var-arguments">name</var><a class="copiable-link" href='#index-_002edo'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-do"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005cn_005b_002ecp_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.cp]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002ecp_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002ecp-1"></a>
<p>The <code class="code">do</code> request interprets the string, request, diversion, or
macro <var class="var">name</var> (along with any further arguments) with compatibility
mode disabled. Compatibility mode is restored (only if it was active)
when the <em class="emph">expansion</em> of <var class="var">name</var> is interpreted; that is, the
restored compatibility state applies to the contents of the macro,
string, or diversion <var class="var">name</var> as well as data read from files or pipes
if <var class="var">name</var> is any of the <code class="code">so</code>, <code class="code">soquiet</code>, <code class="code">mso</code>,
<code class="code">msoquiet</code>, or <code class="code">pso</code> requests.
</p>
<p>The following example illustrates several aspects of <code class="code">do</code> behavior.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de mac1
FOO
..
.de1 mac2
groff
.mac1
..
.de mac3
compatibility
.mac1
..
.de ma
\\$1
..
.cp 1
.do mac1
.do mac2 \" mac2, defined with .de1, calls "mac1"
.do mac3 \" mac3 calls "ma" with argument "c1"
.do mac3 \[ti] \" groff syntax accepted in .do arguments
⇒ FOO groff FOO compatibility c1 ~
</pre></div></div>
<p>The read-only register <code class="code">.cp</code>, meaningful only when dereferenced
from a <code class="code">do</code> request, is 1 if compatibility mode was on when
the <code class="code">do</code> request was encountered, and 0 if it was not. This
register is specialized and may require a statement of rationale.
</p>
<p>When writing macro packages or documents that use GNU <code class="code">troff</code>
features and which may be mixed with other packages or documents that do
not—common scenarios include serial processing of man pages or use of
the <code class="code">so</code> or <code class="code">mso</code> requests—you may desire correct operation
regardless of compatibility mode enablement in the surrounding context.
It may occur to you to save the existing value of ‘<samp class="samp">\n(.C</samp>’ into a
register, say, ‘<samp class="samp">_C</samp>’, at the beginning of your file, turn
compatibility mode off with ‘<samp class="samp">.cp 0</samp>’, then restore it from that
register at the end with ‘<samp class="samp">.cp \n(_C</samp>’. At the same time, a modular
design of a document or macro package may lead you to multiple layers of
inclusion. You cannot use the same register name everywhere lest you
“clobber” the value from a preceding or enclosing context. The
two-character register name space of <abbr class="acronym">AT&T</abbr> <code class="code">troff</code> is
confining and mnemonically challenging; you may wish to use the more
capacious name space of GNU <code class="code">troff</code>. However, attempting ‘<samp class="samp">.nr
_my_saved_C \n(.C</samp>’ will not work in compatibility mode; the register
name is too long. “This is exactly what <code class="code">do</code> is for,” you think,
‘<samp class="samp">.do nr _my_saved_C \n(.C</samp>’. The foregoing will always save zero to
your register, because <code class="code">do</code> turns compatibility mode <em class="emph">off</em>
while it interprets its argument list.
</p>
<p>To robustly save compatibility mode before switching it off, use
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.do nr _my_saved_C \n[.cp]
.cp 0
</pre></div></div>
<p>at the beginning of your file, followed by
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.cp \n[_my_saved_C]
.do rr _my_saved_C
</pre></div></div>
<p>at the end. As in the C language, we all have to share one big
name space, so choose a register name that is unlikely to collide with
other uses.
</p></dd></dl>
<a class="index-entry-id" id="index-input-level-in-delimited-arguments"></a>
<a class="index-entry-id" id="index-interpolation-depth-in-delimited-arguments"></a>
<a class="index-entry-id" id="index-delimited-arguments_002c-incompatibilities-with-AT_0026T-troff"></a>
<p>Normally, GNU <code class="code">troff</code> preserves the interpolation depth in
delimited arguments, but not in compatibility mode.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.ds xx '
\w'abc\*(xxdef'
⇒ 168 <span class="r">(normal mode on a terminal device)</span>
⇒ 72def' <span class="r">(compatibility mode on a terminal device)</span>
</pre></div></div>
<a class="index-entry-id" id="index-_005cf_002c-incompatibilities-with-AT_0026T-troff"></a>
<a class="index-entry-id" id="index-_005cH_002c-incompatibilities-with-AT_0026T-troff"></a>
<a class="index-entry-id" id="index-_005cs_002c-incompatibilities-with-AT_0026T-troff"></a>
<a class="index-entry-id" id="index-_005cS_002c-incompatibilities-with-AT_0026T-troff"></a>
<p>Furthermore, the escape sequences <code class="code">\f</code>, <code class="code">\H</code>, <code class="code">\m</code>,
<code class="code">\M</code>, <code class="code">\R</code>, <code class="code">\s</code>, and <code class="code">\S</code> are transparent for the
purpose of recognizing a control character at the beginning of a line
only in compatibility mode. For example, this code produces bold output
in both cases, but the text differs.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de xx
Hello!
..
\fB.xx\fP
⇒ .xx <span class="r">(normal mode)</span>
⇒ Hello! <span class="r">(compatibility mode)</span>
</pre></div></div>
<a class="index-entry-id" id="index-_005cs_002c-incompatibilities-with-AT_0026T-troff-1"></a>
<p>Normally, the syntax form <code class="code">\s</code><var class="var">n</var> accepts only a single
character (a digit) for <var class="var">n</var>, consistently with other forms that
originated in <abbr class="acronym">AT&T</abbr> <code class="code">troff</code>, like <code class="code">\*</code>, <code class="code">\$</code>,
<code class="code">\f</code>, <code class="code">\g</code>, <code class="code">\k</code>, <code class="code">\n</code>, and <code class="code">\z</code>. In
compatibility mode only, a non-zero <var class="var">n</var> must be in the range
4–39. Legacy documents relying upon this quirk of parsing<a class="footnote" id="DOCF120" href="groff.html_fot.html#FOOT120"><sup>120</sup></a> should be migrated to another
<code class="code">\s</code> form.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Safer-Mode.html">Safer Mode</a>, Previous: <a href="Other-Differences.html">Other Differences</a>, Up: <a href="Implementation-Differences.html">Implementation Differences</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
