Debian Codegraph @

upstream/opensuse-tumbleweed/man7/groff_trace.7

raw
1 .TH groff_trace 7 "2 March 2026" "groff 1.23.0"
2 .SH Name
3 groff_trace \- macros for debugging GNU
4 .I roff
5 documents
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 2002-2022 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of groff, the GNU roff type-setting system.
15 .\"
16 .\" Permission is granted to copy, distribute and/or modify this
17 .\" document under the terms of the GNU Free Documentation License,
18 .\" Version 1.3 or any later version published by the Free Software
19 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
20 .\" and with no Back-Cover Texts.
21 .\"
22 .\" A copy of the Free Documentation License is included as a file
23 .\" called FDL in the main directory of the groff source package.
24 .
25 .
26 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
27 .do nr *groff_groff_trace_7_man_C \n[.cp]
28 .cp 0
29 .
30 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
31 .nr do-fallback 0
32 .if !\n(.f .nr do-fallback 1 \" mandoc
33 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
34 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
35 .if \n[do-fallback] \{\
36 . de MR
37 . ie \\n(.$=1 \
38 . I \%\\$1
39 . el \
40 . IR \%\\$1 (\\$2)\\$3
41 . .
42 .\}
43 .rr do-fallback
44 .
45 .
46 .\" ====================================================================
47 .SH Synopsis
48 .\" ====================================================================
49 .
50 .SY "groff \-m trace"
51 .RI [ option\~ .\|.\|.\&]
52 .RI [ file\~ .\|.\|.]
53 .YS
54 .
55 .
56 .\" ====================================================================
57 .SH Description
58 .\" ====================================================================
59 .
60 .I trace
61 is a macro package for the
62 .MR groff 7
63 document formatting system,
64 designed as an aid for debugging documents written in its language.
65 .
66 It issues a message to the standard error stream upon entry to and exit
67 from each macro call.
68 .
69 This can ease the process of isolating errors in macro definitions.
70 .
71 .
72 .P
73 Activate the package by specifying the command-line option
74 .RB \[lq] \-m\~trace \[rq]
75 to the formatter program
76 (often
77 .MR groff 1 ).
78 .
79 You can achieve finer control by including the macro file within the
80 document;
81 invoke the
82 .B mso
83 request,
84 as in
85 .RB \[lq] .mso\~trace.tmac \[rq].
86 .
87 Only macros that are defined after this invocation are traced.
88 .
89 If the
90 .B trace\-full
91 register is set to a true value,
92 as with the command-line option
93 .RB \[lq] \-r\~trace\-full=1 \[rq],
94 register and string assignments,
95 along with some other requests,
96 are traced also.
97 .
98 If another macro package should be traced as well,
99 specify it after
100 .RB \[lq] \-m\~trace \[rq]
101 on the command line.
102 .
103 .
104 .P
105 The macro file
106 .I trace.tmac
107 is unusual because it does not contain any macros to be called by a
108 user.
109 .
110 Instead,
111 .IR groff 's
112 macro definition and alteration facilities are wrapped such that they
113 display diagnostic messages.
114 .
115 .
116 .\" ====================================================================
117 .SS Limitations
118 .\" ====================================================================
119 .
120 Because
121 .I trace.tmac
122 wraps the
123 .B de
124 request
125 (and its cousins),
126 macro arguments are expanded one level more.
127 .
128 This causes problems if an argument uses four or more backslashes to
129 delay interpretation of an escape sequence.
130 .
131 For example,
132 the macro call
133 .
134 .RS
135 .EX
136 \&.foo \[rs]\[rs]\[rs]\[rs]n[bar]
137 .EE
138 .RE
139 .
140 normally passes \[lq]\[rs]\[rs]n[bar]\[rq] to macro \[lq]foo\[rq],
141 but with
142 .B de
143 redefined,
144 it passes \[lq]\[rs]n[bar]\[rq] instead.
145 .
146 .
147 .P
148 The solution to this problem is to use
149 .IR groff 's
150 .B \[rs]E
151 escape sequence,
152 an escape character that is not interpreted in copy mode.
153 .
154 .RS
155 .EX
156 \&.foo \[rs]En[bar]
157 .EE
158 .RE
159 .
160 .
161 .\" ====================================================================
162 .SH Examples
163 .\" ====================================================================
164 .
165 We will illustrate
166 .I trace.tmac
167 using the shell's \[lq]here document\[rq] feature to supply
168 .I groff
169 with a document
170 on the standard input stream.
171 .
172 Since we are interested only in diagnostic messages appearing on the
173 standard error stream,
174 we discard the formatted output by redirecting the standard output
175 stream to
176 .IR /dev/null .
177 .
178 .
179 .\" ====================================================================
180 .SS "Observing nested macro calls"
181 .\" ====================================================================
182 .
183 Macro calls can be nested,
184 even with themselves.
185 .
186 Tracing recurses along with them;
187 this feature can help to detangle complex call stacks.
188 .
189 .
190 .RS
191 .P
192 .EX
193 .RB $\~ "cat <<EOF | groff \-m trace > /dev/null
194 .B .de countdown
195 .B . nop \[rs]\[rs]$1
196 .B . nr count (\[rs]\[rs]$1 - 1)
197 .B . if \[rs]\[rs]n[count] .countdown \[rs]\[rs]n[count]
198 .B ..
199 .B .countdown 3
200 .B blastoff
201 .B EOF
202 \~*** .de countdown
203 \~*** de trace enter: .countdown "3"
204 \~\~*** de trace enter: .countdown "2"
205 \~\~\~*** de trace enter: .countdown "1"
206 \~\~\~*** trace exit: .countdown "1"
207 \~\~*** trace exit: .countdown "2"
208 \~*** trace exit: .countdown "3"
209 .EE
210 .RE
211 .
212 .
213 .\" ====================================================================
214 .SS "Tracing with the mso request"
215 .\" ====================================================================
216 .
217 Now let us activate tracing within the document,
218 not with a command-line option.
219 .
220 We might do this when using a macro package like
221 .I ms
222 or
223 .IR mom ,
224 where we may not want to be distracted by traces of macros we didn't
225 write.
226 .
227 .
228 .RS
229 .P
230 .EX
231 .RB $\~ "cat <<EOF | groff -ms > /dev/null"
232 .B .LP
233 .B This is my introductory paragraph.
234 .B .mso trace.tmac
235 .B .de Mymac
236 .B ..
237 .B .Mymac
238 .B .PP
239 .B Let us review the existing literature.
240 .B EOF
241 \~*** .de Mymac
242 \~*** de trace enter: .Mymac
243 \~*** trace exit: .Mymac
244 .EE
245 .RE
246 .
247 .
248 .P
249 As tracing was not yet active when the macros \[lq]LP\[rq] and
250 \[lq]PP\[rq] were defined
251 (by
252 .IR s.tmac ),
253 their calls were not traced;
254 contrast with the macro \[lq]Mymac\[rq].
255 .
256 .
257 .br
258 .ne 3v
259 .\" ====================================================================
260 .SH Files
261 .\" ====================================================================
262 .
263 .TP
264 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:trace\:.tmac
265 implements the package.
266 .
267 .
268 .\" ====================================================================
269 .SH Authors
270 .\" ====================================================================
271 .
272 .I trace.tmac
273 was written by James Clark.
274 .
275 This document was written by
276 .MT groff\-bernd\:.warken\-72@\:web\:.de
277 Bernd Warken
278 .ME
279 and
280 .MT g.branden\:.robinson@\:gmail\:.com
281 G.\& Branden Robinson
282 .ME .
283 .
284 .
285 .\" ====================================================================
286 .SH "See also"
287 .\" ====================================================================
288 .
289 .IR "Groff: The GNU Implementation of troff" ,
290 by Trent A.\& Fisher and Werner Lemberg,
291 is the primary
292 .I groff
293 manual.
294 .
295 You can browse it interactively with \[lq]info groff\[rq].
296 .
297 .
298 .TP
299 .MR groff 1
300 gives an overview of the
301 .I groff
302 document formatting system.
303 .
304 .
305 .TP
306 .MR troff 1
307 supplies details of the
308 .B \-m
309 command-line option.
310 .
311 .
312 .TP
313 .MR groff_tmac 5
314 offers a survey of
315 .I groff
316 macro packages.
317 .
318 .
319 .TP
320 .MR groff 7
321 is a reference manual for the
322 .I groff
323 language.
324 .
325 .
326 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
327 .cp \n[*groff_groff_trace_7_man_C]
328 .do rr *groff_groff_trace_7_man_C
329 .
330 .
331 .\" Local Variables:
332 .\" fill-column: 72
333 .\" mode: nroff
334 .\" End:
335 .\" vim: set filetype=groff textwidth=72: