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