Debian Codegraph @

upstream/debian-trixie/man7/groff_trace.7

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