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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
|
<!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>Debugging (The GNU Troff Manual)</title>
<meta name="description" content="Debugging (The GNU Troff Manual)">
<meta name="keywords" content="Debugging (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="GNU-troff-Reference.html" rel="up" title="GNU troff Reference">
<link href="Implementation-Differences.html" rel="next" title="Implementation Differences">
<link href="Gtroff-Internals.html" rel="prev" title="Gtroff Internals">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
p.flushright-paragraph {text-align:right}
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="section-level-extent" id="Debugging">
<div class="nav-panel">
<p>
Next: <a href="Implementation-Differences.html" accesskey="n" rel="next">Implementation Differences</a>, Previous: <a href="Gtroff-Internals.html" accesskey="p" rel="prev"><code class="code">gtroff</code> Internals</a>, Up: <a href="GNU-troff-Reference.html" accesskey="u" rel="up">GNU <code class="code">troff</code> Reference</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>
<h3 class="section" id="Debugging-1">5.37 Debugging</h3>
<a class="index-entry-id" id="index-debugging"></a>
<div class="flushright"><p class="flushright-paragraph"><i class="slanted">Standard troff voodoo, just put a power of two backslashes in
front of it until it works and if you still have problems add a \c.</i>
— Ron Natalie
</p></div>
<p>GNU <code class="code">troff</code> is not the easiest language to debug, in part thanks to
its design features of recursive interpolation and the use of
multi-stage pipeline processing in the surrounding system. Nevertheless
there exist several features useful for troubleshooting.
</p>
<p>Preprocessors use the <code class="code">lf</code> request to preserve the identity of the
line numbers and names of input files. GNU <code class="code">troff</code> emits a variety
of error diagnostics and supports several categories of warning; the
output of these can be selectively suppressed. A trace of the
formatter’s input processing stack can be emitted when errors or
warnings occur by means of GNU <code class="code">troff</code>’s <samp class="option">-b</samp> option, or
produced on demand with the <code class="code">backtrace</code> request. The <code class="code">tm</code>
and related requests can be used to emit customized diagnostic messages
or for instrumentation while troubleshooting. The <code class="code">ex</code> and
<code class="code">ab</code> requests cause early termination with successful and error
exit codes respectively, to halt further processing when continuing
would be fruitless. Examine the state of the formatter with requests
that write lists of defined names (macros, strings, and diversions),
environments, registers, and page location traps to the standard error
stream.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002elf"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.lf</code></strong> <var class="def-var-arguments">line [<span class="r"><i class="slanted">file</i></span>]</var><a class="copiable-link" href='#index-_002elf'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-lf"></a>
<a class="index-entry-id" id="index-soelim"></a>
<a class="index-entry-id" id="index-multi_002dfile-documents"></a>
<a class="index-entry-id" id="index-documents_002c-multi_002dfile"></a>
<a class="index-entry-id" id="index-setting-input-line-number-_0028lf_0029"></a>
<a class="index-entry-id" id="index-input-line-number_002c-setting-_0028lf_0029"></a>
<a class="index-entry-id" id="index-number_002c-input-line_002c-setting-_0028lf_0029"></a>
<p>Set the input line number (and, optionally, the file name) GNU
<code class="code">troff</code> shall use for error and warning messages. <var class="var">line</var> is
the input line number of the <em class="emph">next</em> line. Without an argument, the
request is ignored.
</p>
<p><code class="code">lf</code>’s primary purpose is to aid the debugging of documents that
undergo preprocessing. Programs like <code class="command">tbl</code> that transform input
in their own languages into <code class="code">roff</code> requests use it so that any
diagnostic messages emitted by <code class="code">troff</code> correspond to the source
document.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002etm"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tm</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etm'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-tm"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002etm1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tm1</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etm1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-tm1"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_002etmc"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tmc</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etmc'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-tmc"></a>
<a class="index-entry-id" id="index-printing-to-stderr-_0028tm_002c-tm1_002c-tmc_0029"></a>
<a class="index-entry-id" id="index-stderr_002c-printing-to-_0028tm_002c-tm1_002c-tmc_0029"></a>
<p>Send <var class="var">message</var>, which consumes the remainder of the input line and
cannot contain special characters, to the standard error stream,
followed by a newline. Leading spaces in <var class="var">message</var> are ignored.
</p>
<p><code class="code">tm1</code> is similar, but recognizes and strips a leading neutral
double quote from <var class="var">message</var> to allow the embedding of leading
spaces.
</p>
<p><code class="code">tmc</code> works as <code class="code">tm1</code>, but does not append a newline.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002eab"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ab</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">message</i></span>]</var><a class="copiable-link" href='#index-_002eab'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ab"></a>
<a class="index-entry-id" id="index-aborting-_0028ab_0029"></a>
<p>Write any <var class="var">message</var> to the standard error stream (like <code class="code">tm</code>)
and then abort GNU <code class="code">troff</code>; that is, stop processing and terminate
with a failure status.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002eex"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ex</code></strong><a class="copiable-link" href='#index-_002eex'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ex"></a>
<a class="index-entry-id" id="index-ex-request_002c-use-in-debugging"></a>
<a class="index-entry-id" id="index-exiting-_0028ex_0029"></a>
<p>Exit GNU <code class="code">troff</code>; that is, stop processing and terminate with a
successful status. To stop processing only the current file, use the
<code class="code">nx</code> request; see <a class="ref" href="I_002fO.html">I/O</a>.
</p></dd></dl>
<p>When doing something involved, it is useful to leave the debugging
statements in the code and have them turned on by a command-line flag.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.if \n[DB] .tm debugging output
</pre></div></div>
<p>To activate such statements, use the <samp class="option">-r</samp> option to set the
register.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">groff -rDB=1 <i class="slanted">file</i>
</pre></div></div>
<p>If it is known in advance that there are many errors and no useful
output, GNU <code class="code">troff</code> can be forced to suppress formatted output with
the <samp class="option">-z</samp> option.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002epev"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pev</code></strong><a class="copiable-link" href='#index-_002epev'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-pev"></a>
<a class="index-entry-id" id="index-dumping-environments-_0028pev_0029"></a>
<a class="index-entry-id" id="index-environments_002c-dumping-_0028pev_0029"></a>
<p>Report the state of the current environment followed by that of all
other environments to the standard error stream.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002epm"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pm</code></strong><a class="copiable-link" href='#index-_002epm'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-pm"></a>
<a class="index-entry-id" id="index-dumping-symbol-table-_0028pm_0029"></a>
<a class="index-entry-id" id="index-symbol-table_002c-dumping-_0028pm_0029"></a>
<p>Report, to the standard error stream, the names of all defined macros,
strings, and diversions with their sizes in bytes.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002epnr"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pnr</code></strong><a class="copiable-link" href='#index-_002epnr'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-pnr"></a>
<a class="index-entry-id" id="index-dumping-registers-_0028pnr_0029"></a>
<a class="index-entry-id" id="index-registers_002c-dumping-_0028pnr_0029"></a>
<p>Report the names and contents of all currently defined registers to the
standard error stream.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002eptr"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ptr</code></strong><a class="copiable-link" href='#index-_002eptr'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ptr"></a>
<a class="index-entry-id" id="index-dumping-page-location-traps-_0028ptr_0029"></a>
<a class="index-entry-id" id="index-listing-page-location-traps-_0028ptr_0029"></a>
<a class="index-entry-id" id="index-traps_002c-page-location_002c-dumping-_0028ptr_0029"></a>
<a class="index-entry-id" id="index-traps_002c-page-location_002c-listing-_0028ptr_0029"></a>
<p>Report the names and positions of all page location traps to the
standard error stream. Empty slots in the list, where a trap has been
planted but subsequently (re)moved, are printed as well.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002efl"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.fl</code></strong><a class="copiable-link" href='#index-_002efl'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-fl"></a>
<a class="index-entry-id" id="index-flush-output-_0028fl_0029"></a>
<a class="index-entry-id" id="index-output_002c-flush-_0028fl_0029"></a>
<a class="index-entry-id" id="index-interactive-use-of-gtroff"></a>
<a class="index-entry-id" id="index-gtroff_002c-interactive-use"></a>
<p>Instruct <code class="code">gtroff</code> to flush its output immediately. The intent is
for interactive use, but this behaviour is currently not implemented in
<code class="code">gtroff</code>. Contrary to Unix <code class="code">troff</code>, TTY output is sent to a
device driver also (<code class="code">grotty</code>), making it non-trivial to communicate
interactively.
</p>
<p>This request causes a line break.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ebacktrace"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.backtrace</code></strong><a class="copiable-link" href='#index-_002ebacktrace'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-backtrace"></a>
<a class="index-entry-id" id="index-backtrace-of-input-stack-_0028backtrace_0029"></a>
<a class="index-entry-id" id="index-input-stack_002c-backtrace-_0028backtrace_0029"></a>
<p>Write the state of the input stack to the standard error stream.
</p>
<p>Consider the following in a file <samp class="file">test</samp>.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de xxx
. backtrace
..
.de yyy
. xxx
..
.
.yyy
error→ troff: backtrace: 'test':2: macro 'xxx'
error→ troff: backtrace: 'test':5: macro 'yyy'
error→ troff: backtrace: file 'test':8
</pre></div></div>
<p>The <samp class="option">-b</samp> option of GNU <code class="code">troff</code> causes a backtrace to be
generated on each error or warning. Some warnings have to be enabled;
See <a class="xref" href="Warnings.html">Warnings</a>.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005bslimit_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[slimit]</code></strong><a class="copiable-link" href='#index-_005cn_005bslimit_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-slimit"></a>
<a class="index-entry-id" id="index-input-stack_002c-setting-limit"></a>
<p>If greater than 0, sets the maximum quantity of objects on GNU
<code class="code">troff</code>’s internal input stack. If less than or equal to 0,
there is no limit: recursion can continue until program memory is
exhausted. The default is 1,000.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ewarnscale"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.warnscale</code></strong> <var class="def-var-arguments">su</var><a class="copiable-link" href='#index-_002ewarnscale'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-warnscale"></a>
<p>Set the scaling unit used in certain warnings to <var class="var">su</var>, which can take the values ‘<samp class="samp">u</samp>’, ‘<samp class="samp">i</samp>’, ‘<samp class="samp">c</samp>’,
‘<samp class="samp">p</samp>’, and ‘<samp class="samp">P</samp>’. The default is ‘<samp class="samp">i</samp>’.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002espreadwarn"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.spreadwarn</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">limit</i></span>]</var><a class="copiable-link" href='#index-_002espreadwarn'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-spreadwarn"></a>
<p>Emit a <code class="code">break</code> warning if the additional space inserted for each
space between words in an output line adjusted to both margins with
‘<samp class="samp">.ad b</samp>’<!-- /@w --> is larger than or equal to <var class="var">limit</var>. A negative
value is treated as zero; an absent argument toggles the warning on and
off without changing <var class="var">limit</var>. The default scaling unit is ‘<samp class="samp">m</samp>’.
At startup, <code class="code">spreadwarn</code> is inactive and <var class="var">limit</var> is 3<span class="dmn">m</span>.
</p>
<p>For example,
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.spreadwarn 0.2m
</pre></div></div>
<p>causes a warning if <code class="code">break</code> warnings are not suppressed and
<code class="code">gtroff</code> must add 0.2<span class="dmn">m</span> or more for each inter-word space in a
line. See <a class="xref" href="Warnings.html">Warnings</a>.
</p></dd></dl>
<a class="index-entry-id" id="index-warnings"></a>
<p>GNU <code class="code">troff</code> has command-line options for reporting warnings
(<samp class="option">-w</samp>) and backtraces (<samp class="option">-b</samp>) when a warning or an error
occurs.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ewarn"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.warn</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">n</i></span>]</var><a class="copiable-link" href='#index-_002ewarn'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-warn"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005cn_005b_002ewarn_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.warn]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002ewarn_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002ewarn-1"></a>
<a class="index-entry-id" id="index-warning-level-_0028warn_0029"></a>
<p>Select the categories, or “types”, of reported warnings.
<var class="var">n</var> is the sum of the numeric codes associated with each
warning category that is to be enabled; all other categories are
disabled. The categories and their associated codes are listed in
<a class="ref" href="Warnings.html">Warnings</a>. For example, ‘<samp class="samp">.warn 0</samp>’ disables all warnings, and
‘<samp class="samp">.warn 1</samp>’ disables all warnings except those about missing glyphs.
If no argument is given, all warning categories are enabled.
</p>
<p>The read-only register <code class="code">.warn</code> contains the sum of the numeric
codes of enabled warning categories.
</p></dd></dl>
<ul class="mini-toc">
<li><a href="Warnings.html" accesskey="1">Warnings</a></li>
</ul>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Implementation-Differences.html">Implementation Differences</a>, Previous: <a href="Gtroff-Internals.html"><code class="code">gtroff</code> Internals</a>, Up: <a href="GNU-troff-Reference.html">GNU <code class="code">troff</code> Reference</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>
|
