| blob | bc1c98c17bb3aec474671aafba0b969f7f5e0a07 |
1 .
2 .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
3 .SH NAME
4 groff_trace \- groff macro package trace.tmac
5 .SH SYNOPSIS
6 .\" The .SH was moved to this place to make `apropos' happy.
7 .
8 .
9 .\" --------------------------------------------------------------------
10 .\" Legalize
11 .\" --------------------------------------------------------------------
12 .
13 .ig
14 groff_trace.7
16 File position: <groff-source>/tmac/groff_trace.man
18 Last update: 14 July 2002
20 This file is part of groff, the GNU roff type-setting system.
22 Copyright (C) 2002 Free Software Foundation, Inc.
23 written by Bernd Warken <bwarken@mayn.de>
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.1 or
27 any later version published by the Free Software Foundation; with the
28 Invariant Sections being this .ig-section and AUTHOR, with no
29 Front-Cover Texts, and with no Back-Cover Texts.
31 A copy of the Free Documentation License is included as a file called
32 FDL in the main directory of the groff source package.
33 ..
34 .
35 .\" --------------------------------------------------------------------
36 .\" Setup
37 .\" --------------------------------------------------------------------
38 .
39 .do nr groff_trace_C \n[.C]
40 .cp 0
41 .
42 .mso www.tmac
43 .
44 .if n \{\
45 . mso tty-char.tmac
46 . ftr CR R
47 . ftr CI I
48 . ftr CB B
49 .\}
50 .
51 .ds Ellipsis .\|.\|.\&\"
52 .
53 .\" Global static variables for inter-macro communication
54 .rr @+Example_font
55 .
56 .\" --------------------------------------------------------------------
57 .\" setup for the macro definitions below
58 .\"
59 .\" naming: namespace:category_macro.variable_name (experimental)
60 .
61 .\" --------------------------------------------------------------------
62 .\" configuration of prompt for `.Shell_cmd'* macros
63 .ds trace:Shell_cmd.prompt_text sh#\" prompt for shell commands
64 .ds trace:Shell_cmd+.prompt_text >\" prompt on continuation lines
65 .ds trace:Shell_cmd_base.prompt_font I\" font for prompts
66 .
67 .\" automatically determine setup from the configuration above
68 .als @f trace:Shell_cmd_base.prompt_font\"
69 .als @t trace:Shell_cmd.prompt_text\"
70 .als @t+ trace:Shell_cmd+.prompt_text\"
71 .ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed
72 .ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed
73 .nr @w \w'\*[trace:Shell_cmd.prompt]'\"
74 .nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\"
75 .ft \*[@f]
76 .\" Full prompt width is maximum of texts plus 1m
77 .nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
78 .ft
79 .rm @f
80 .rm @f+
81 .rm @t
82 .rm @t+
83 .rr @w
84 .rr @w+
85 .
86 .\"--------------------------------------------------------------------
87 .\" Ignore all arguments like a comment, even after a .eo call.
88 .de c
89 ..
90 .c --------------------------------------------------------------------
91 .de BIR
92 . ie (\\n[.$] < 3) \
93 . BI \\$@
94 . el \{\
95 . ds @tmp@ \fB\\$1\f[]\fI\\$2\f[]
96 . shift 2
97 . Text \\*[@tmp@]\fR\\$*\f[]
98 . rm @tmp@
99 . \}
100 ..
101 .c --------------------------------------------------------------------
102 .c .Env_var (<env_var_name> [<punct>])
103 .c
104 .c Display an environment variable, with optional punctuation.
105 .c
106 .de Env_var
107 . nh
108 . SM
109 . Text \f[CB]\\$1\f[]\\$2
110 . hy
111 ..
112 .c --------------------------------------------------------------------
113 .c .Error (<text>...)
114 .c
115 .c Print error message to terminal and abort.
116 .c
117 .de Error
118 . tm \\$*
119 . ab
120 ..
121 .c --------------------------------------------------------------------
122 .de Example
123 . if r@+Example_font \
124 . Error previous .Example was not terminated by a ./Example
125 . nr @+Example_font \\n[.f]
126 . nh
127 . nf
128 .c RS \\n[trace:Shell_cmd_base.prompt_width]u
129 . ft CR
130 ..
131 .c --------------------------------------------------------------------
132 .de /Example
133 . if !r@+Example_font \
134 . Error no previous call to .Example
135 . ft \\n[@+Example_font]
136 .c RE
137 . fi
138 . hy
139 . rr @+Example_font
140 ..
141 .c --------------------------------------------------------------------
142 .de Macdef
143 . if (\\n[.$] <= 0) \
144 . Error \\$0 needs at least one argument.
145 . ds @s .\f[B]\\$1\f[]\"
146 . shift
147 . if (\\n[.$] > 0) \
148 . as @s \~\f[I]\\$*\f[]\"
149 . IP \\*[@s]
150 . rm @s
151 ..
152 .c --------------------------------------------------------------------
153 .de Macdef+
154 . br
155 . ns
156 . Macdef \\$@
157 ..
158 .c --------------------------------------------------------------------
159 .c .Shell_cmd (<CR> [<CI>] ...)
160 .c
161 .c A shell command line; display args alternating in fonts CR and CI.
162 .c
163 .c Examples:
164 .c .Shell_cmd "groffer --dpi 100 file"
165 .c result: `sh# groffer --dpi 100 file'
166 .c with 'sh#' in font I, the rest in CR
167 .c
168 .c .Shell_cmd groffer\~--dpi\~100\~file
169 .c result: the same as above
170 .c
171 .c .Shell_cmd "groffer --dpi=" value " file"
172 .c result: sh# groffer --dpi=value file
173 .c with `groffer --dpi=' and `file' in CR; `value' in CI
174 .c
175 .c .Shell_cmd groffer\~--dpi= value \~file
176 .c result: the same as the previous example
177 .c
178 .de Shell_cmd
179 . trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@
180 ..
181 .c --------------------------------------------------------------------
182 .c .Shell_cmd+ (<CR> [<CI>] ...)
183 .c
184 .c A continuation line for .Shell_cmd.
185 .c
186 .de Shell_cmd+
187 . trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@
188 ..
189 .c --------------------------------------------------------------------
190 .c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...])
191 .c
192 .c A shell command line; display args alternating in fonts CR and CI.
193 .c Internal, do not use directly.
194 .c
195 .c Globals: read-only register @.Shell_cmd_width
196 .c
197 .de trace:Shell_cmd_base
198 . if (\\n[.$] <= 0) \
199 . return
200 . nr @+font \\n[.f]\"
201 . ds @prompt \\$1\"
202 . ft CR
203 . c gap between prompt and command
204 . nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
205 . ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
206 . shift
207 . ds @cf CR\"
208 . while (\\n[.$] > 0) \{\
209 . as @res \\f[\\*[@cf]]\\$1\"
210 . shift
211 . ie '\\*[@cf]'CR' \
212 . ds @cf I\"
213 . el \
214 . ds @cf CR\"
215 . \}
216 . br
217 . ad l
218 . nh
219 . nf
220 . Text \\*[@res]\"
221 . fi
222 . hy
223 . ad
224 . br
225 . ft \\n[@+font]
226 . rr @+font
227 . rr @+gap
228 . rm @cf
229 . rm @res
230 ..
231 .c --------------------------------------------------------------------
232 .c .Text (<text>...)
233 .c
234 .c Treat the arguments as text, no matter how they look.
235 .c
236 .de Text
237 . if (\\n[.$] == 0) \
238 . return
239 . nop \)\\$*\)
240 ..
241 .c --------------------------------------------------------------------
242 .c .Topic ([<indent>])
243 .c
244 .c A bulleted paragraph.
245 .c
246 .de Topic
247 . ie (\\n[.$] = 0) \
248 . .ds @indent 2m\"
249 . el \
250 . .ds @indent \\$1\"
251 . TP \\*[@indent]
252 . Text \[bu]
253 . rm @indent
254 ..
255 .c --------------------------------------------------------------------
256 .c .TP+ ()
257 .c
258 .c Continuation line for .TP header.
259 .c
260 .de TP+
261 . br
262 . ns
263 . TP \\$1
264 ..
265 .c --------------------------------------------------------------------
266 .de 'char
267 . ds @tmp@ `\f(CR\\$1\f[]'
268 . shift
269 . Text \\*[@tmp@]\\$*
270 . rm @tmp@
271 ..
272 .c --------------------------------------------------------------------
273 .de option
274 . ds @tmp@ \f(CB\\$1\f[]
275 . shift 1
276 . Text \\*[@tmp@]\\$*
277 . rm @tmp@
278 ..
279 .c --------------------------------------------------------------------
280 .de argument
281 . ds @tmp@ \f(CI\\$1\f[]
282 . shift 1
283 . Text \\*[@tmp@]\\$*
284 . rm @tmp@
285 ..
286 .c --------------------------------------------------------------------
287 .de request
288 . ds @tmp@ \f(CB\\$1\f[]
289 . shift 1
290 . Text .\\*[@tmp@]\\$*
291 . rm @tmp@
292 ..
293 .c --------------------------------------------------------------------
294 .de escape
295 . ds @tmp@ \f[CB]\\$1\f[]
296 . shift 1
297 . Text \[rs]\\*[@tmp@]\\$*
298 . rm @tmp@
299 ..
300 .
301 .
302 .\" --------------------------------------------------------------------
303 .\" SH SYNOPSIS
304 .\" --------------------------------------------------------------------
305 .
306 .B groff -m trace
307 .RI [ options\*[Ellipsis] ]
308 .RI [ files\*[Ellipsis] ]
309 .
310 .
311 .P
312 Elements in brackets denote optional arguments, and the ellipsis means
313 that there can be any number of arguments of this kind.
314 .
315 .
316 .\" --------------------------------------------------------------------
317 .SH DESCRIPTION
318 .\" --------------------------------------------------------------------
319 .
320 The
321 .I trace
322 macro package of
323 .BR groff (@MAN1EXT@)
324 can be a valuable tool for debugging documents written in the roff
325 formatting language.
326 .
327 A call stack trace is protocolled on standard error, that means, a
328 diagnostic message is emitted on entering and exiting of a macro call.
329 .
330 This greatly eases to track down an error in some macro.
331 .
332 .
333 .P
334 This tracing process is activated by specifying the groff or troff
335 command line option
336 .BR "-m\~trace" .
337 This works also with the
338 .BR groffer (@MAN1EXT@)
339 viewer program.
340 .
341 A finer control can be obtained by including the macro file within the
342 document by the groff macro call
343 .BR ".mso\~trace.tmac" .
344 Only macros that are defined after this line are traced.
345 .
346 .
347 .P
348 If some other macro package should be traced as well it must be specified
349 after
350 .BR "-m\~trace"
351 on the command line.
352 .
353 .
354 .P
355 The macro file
356 .B trace.tmac
357 is unusual because it does not contain any macros to be called by a
358 user.
359 .
360 Instead, the existing macro definition and appending facilities are
361 modified such that they display diagnostic messages.
362 .
363 .
364 .\" --------------------------------------------------------------------
365 .SH EXAMPLES
366 .\" --------------------------------------------------------------------
367 .
368 .P
369 In the following examples, a roff fragment is fed into groff via
370 standard input.
371 .
372 As we are only interested in the diagnostic messages (standard error)
373 on the terminal, the normal formatted output (standard output) is
374 redirected into the nirvana device
375 .IR /dev/null .
376 The resulting diagnostic messages are displayed directly below the
377 corresponding example.
378 .
379 .
380 .\" --------------------------------------------------------------------
381 .SS "Command line option"
382 .
383 .P
384 .Shell_cmd "echo '."
385 .Shell_cmd+ ".de test_macro"
386 .Shell_cmd+ ".."
387 .Shell_cmd+ ".test_macro"
388 .Shell_cmd+ ".test_macro some dummy arguments"
389 .Shell_cmd+ "' | groff -m trace >/dev/null"
390 .P
391 .Example
392 *** de trace enter: test_macro
393 *** trace exit: test_macro
394 *** de trace enter: test_macro "some" "dummy" "arguments"
395 *** trace exit: test_macro "some" "dummy" "arguments"
396 ./Example
397 .
398 .P
399 The entry and the exit of each macro call is displayed on the terminal
400 (standard output) \[em] together with the arguments (if any).
401 .
402 .
403 .\" --------------------------------------------------------------------
404 .SS "Nested macro calls"
405 .
406 .P
407 .Shell_cmd "echo '."
408 .Shell_cmd+ ".de child"
409 .Shell_cmd+ ".."
410 .Shell_cmd+ ".de parent"
411 .Shell_cmd+ ".child"
412 .Shell_cmd+ ".."
413 .Shell_cmd+ ".parent"
414 .Shell_cmd+ "' | groff -m trace >/dev/null"
415 .P
416 .Example
417 *** de trace enter: parent
418 *** de trace enter: child
419 *** trace exit: child
420 *** trace exit: parent
421 ./Example
422 .
423 .P
424 This shows that macro calls can be nested.
425 .
426 This powerful feature can help to tack down quite complex call stacks.
427 .
428 .
429 .\" --------------------------------------------------------------------
430 .SS "Activating with .mso"
431 .
432 .Shell_cmd "echo '."
433 .Shell_cmd+ ".de before"
434 .Shell_cmd+ ..
435 .Shell_cmd+ ".mso trace.tmac"
436 .Shell_cmd+ ".de after"
437 .Shell_cmd+ ..
438 .Shell_cmd+ .before
439 .Shell_cmd+ .after
440 .Shell_cmd+ .before
441 .Shell_cmd+ "' | groff >/dev/null"
442 .P
443 .Example
444 *** de trace enter: after
445 *** trace exit: after
446 ./Example
447 .
448 .P
449 Here, the tracing is activated within the document, not by a command
450 line option.
451 .
452 As tracing was not active when macro
453 .I before
454 was defined, no call of this macro is protocolled; on the other hand,
455 the macro
456 .I after
457 is fully protocolled.
458 .
459 .
460 .\" --------------------------------------------------------------------
461 .SH FILES
462 .\" --------------------------------------------------------------------
463 .
464 The
465 .I trace
466 macros are kept in the file
467 .B trace.tmac
468 located in the
469 .IR "tmac directory" ;
470 see
471 .BR groff_tmac (@MAN5EXT@)
472 for details.
473 .
474 .
475 .\" --------------------------------------------------------------------
476 .SH ENVIRONMENT
477 .\" --------------------------------------------------------------------
478 .
479 .TP
480 .Env_var $GROFF_TMAC_PATH
481 A colon-separated list of additional tmac directories in which to
482 search for macro files; see
483 .BR groff_tmac (@MAN5EXT@)
484 for details.
485 .
486 .
487 .\" --------------------------------------------------------------------
488 .SH AUTHOR
489 .\" --------------------------------------------------------------------
490 .
491 Copyright (C) 2002 Free Software Foundation, Inc.
492 .
493 .P
494 This document is distributed under the terms of the FDL (GNU Free
495 Documentation License) version 1.1 or later.
496 .
497 You should have received a copy of the FDL on your system, it is also
498 available on-line at the
499 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
500 .
501 .P
502 This document is part of
503 .IR groff ,
504 the GNU roff distribution.
505 .
506 It was written by
507 .MTO bwarken@mayn.de "Bernd Warken".
508 .
509 .
510 .\" --------------------------------------------------------------------
511 .SH "SEE ALSO"
512 .\" --------------------------------------------------------------------
513 .
514 .TP
515 .BR groff (@MAN1EXT@)
516 An overview of the groff system.
517 .
518 .
519 .TP
520 .BR troff (@MAN1EXT@)
521 For details on option
522 .BR -m .
523 .
524 .
525 .TP
526 .BR groffer (@MAN1EXT@)
527 A viewer program for all kinds of roff documents.
528 .
529 .
530 .TP
531 .BR groff_tmac (@MAN5EXT@)
532 A general description of groff macro packages.
533 .
534 .
535 .TP
536 .BR groff (@MAN7EXT@)
537 A short reference for the groff formatting language.
538 .
539 .
540 .P
541 A complete reference for all parts of the groff system is found in the
542 groff
543 .BR info (1)
544 file.
545 .
546 .cp \n[groff_trace_C]
547 .
548 .\" Local Variables:
549 .\" mode: nroff
550 .\" End: