Debian Codegraph @

upstream/debian-unstable/man7/groff_trace.7

raw
1 .TH groff_trace 7 "2026-04-22" "groff 1.24.1"
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 2002-2022 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of groff, the GNU roff typesetting 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 .br
165 .ne 3v
166 .\" ====================================================================
167 .SH Files
168 .\" ====================================================================
169 .
170 .TP
171 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:trace\:.tmac
172 implements the package.
173 .
174 .
175 .\" ====================================================================
176 .SH Examples
177 .\" ====================================================================
178 .
179 We will illustrate
180 .I trace.tmac
181 using the shell's \[lq]here document\[rq] feature to supply
182 .I groff
183 with a document
184 on the standard input stream.
185 .
186 Since we are interested only in diagnostic messages appearing on the
187 standard error stream,
188 we discard the formatted output by redirecting the standard output
189 stream to
190 .IR /dev/null .
191 .
192 .
193 .\" ====================================================================
194 .SS "Observing nested macro calls"
195 .\" ====================================================================
196 .
197 Macro calls can be nested,
198 even with themselves.
199 .
200 Tracing recurses along with them;
201 this feature can help to detangle complex call stacks.
202 .
203 .
204 .RS
205 .P
206 .EX
207 .RB $\~ "cat <<EOF | groff \-m trace > /dev/null
208 .B .de countdown
209 .B . nop \[rs]\[rs]$1
210 .B . nr count (\[rs]\[rs]$1 - 1)
211 .B . if \[rs]\[rs]n[count] .countdown \[rs]\[rs]n[count]
212 .B ..
213 .B .countdown 3
214 .B blastoff
215 .B EOF
216 \~*** .de countdown
217 \~*** de trace enter: .countdown "3"
218 \~\~*** de trace enter: .countdown "2"
219 \~\~\~*** de trace enter: .countdown "1"
220 \~\~\~*** trace exit: .countdown "1"
221 \~\~*** trace exit: .countdown "2"
222 \~*** trace exit: .countdown "3"
223 .EE
224 .RE
225 .
226 .
227 .\" ====================================================================
228 .SS "Tracing with the mso request"
229 .\" ====================================================================
230 .
231 Now let us activate tracing within the document,
232 not with a command-line option.
233 .
234 We might do so when employing a macro package like
235 .I ms
236 or
237 .IR mom ,
238 to avoid distraction by traces of macros we didn't write.
239 .
240 .
241 .RS
242 .P
243 .EX
244 .RB $\~ "cat <<EOF | groff -ms > /dev/null"
245 .B .LP
246 .B This is my introductory paragraph.
247 .B .mso trace.tmac
248 .B .de Mymac
249 .B ..
250 .B .Mymac
251 .B .PP
252 .B Let us review the existing literature.
253 .B EOF
254 \~*** .de Mymac
255 \~*** de trace enter: .Mymac
256 \~*** trace exit: .Mymac
257 .EE
258 .RE
259 .
260 .
261 .P
262 As tracing was not yet active when the macros \[lq]LP\[rq] and
263 \[lq]PP\[rq] were defined
264 (by
265 .IR s.tmac ),
266 their calls were not traced;
267 contrast with the macro \[lq]Mymac\[rq].
268 .
269 .
270 .\" ====================================================================
271 .SH Authors
272 .\" ====================================================================
273 .
274 .I trace.tmac
275 was written by James Clark.
276 .
277 This document was written by
278 .MT groff\-bernd\:.warken\-72@\:web\:.de
279 Bernd Warken
280 .ME
281 and
282 .MT g.branden\:.robinson@\:gmail\:.com
283 G.\& Branden Robinson
284 .ME .
285 .
286 .
287 .\" ====================================================================
288 .SH "See also"
289 .\" ====================================================================
290 .
291 .IR "Groff: The GNU Implementation of troff" ,
292 by Trent A.\& Fisher and Werner Lemberg,
293 is the primary
294 .I groff
295 manual.
296 .
297 You can browse it interactively with \[lq]info groff\[rq].
298 .
299 .
300 .TP
301 .MR groff 1
302 gives an overview of the
303 .I groff
304 document formatting system.
305 .
306 .
307 .TP
308 .MR \%troff 1
309 supplies details of the
310 .B \-m
311 command-line option.
312 .
313 .
314 .TP
315 .MR groff_tmac 5
316 offers a survey of
317 .I groff
318 macro packages.
319 .
320 .
321 .TP
322 .MR groff 7
323 is a reference manual for the
324 .I groff
325 language.
326 .
327 .
328 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
329 .cp \n[*groff_groff_trace_7_man_C]
330 .do rr *groff_groff_trace_7_man_C
331 .
332 .
333 .\" Local Variables:
334 .\" fill-column: 72
335 .\" mode: nroff
336 .\" End:
337 .\" vim: set filetype=groff textwidth=72: