4 File position: <groff-source>/tmac/groff_trace.man
6 Last update: 05 Jan 2009
8 This file is part of groff, the GNU roff type-setting system.
10 Copyright (C) 2002, 2006, 2007, 2008, 2009
11 Free Software Foundation, Inc.
13 written by Bernd Warken.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with the
18 Invariant Sections being this .ig-section and AUTHOR, with no
19 Front-Cover Texts, and with no Back-Cover Texts.
21 A copy of the Free Documentation License is included as a file called
22 FDL in the main directory of the groff source package.
25 .ds Ellipsis .\|.\|.\&\"
27 .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
30 groff_trace \- groff macro package trace.tmac
32 .\" --------------------------------------------------------------------
34 .\" --------------------------------------------------------------------
43 .\" --------------------------------------------------------------------
45 .\" --------------------------------------------------------------------
51 can be a valuable tool for debugging documents written in the roff
54 A call stack trace is protocolled on standard error, this is, a
55 diagnostic message is emitted on entering and exiting of a macro call.
57 This greatly eases to track down an error in some macro.
61 This tracing process is activated by specifying the groff or troff
64 This works also with the
65 .BR groffer (@MAN1EXT@)
68 A finer control can be obtained by including the macro file within the
69 document by the groff macro call
70 .BR .mso\ trace.tmac .
71 Only macros that are defined after this line are traced.
75 If command line option
77 is given (or if this register is set in the document), number and string
78 register assignments together with some other requests are traced also.
82 If some other macro package should be traced as well it must be specified
91 is unusual because it does not contain any macros to be called by a
94 Instead, the existing macro definition and appending facilities are
95 modified such that they display diagnostic messages.
98 .\" --------------------------------------------------------------------
100 .\" --------------------------------------------------------------------
102 In the following examples, a roff fragment is fed into groff via
105 As we are only interested in the diagnostic messages (standard error)
106 on the terminal, the normal formatted output (standard output) is
107 redirected to the nirvana device
109 The resulting diagnostic messages are displayed directly below the
110 corresponding example.
113 .\" --------------------------------------------------------------------
114 .SS "Command line option"
124 > .test_macro some dummy arguments
125 > ' | groff -m trace >/dev/null
128 *** de trace enter: .test_macro
129 *** trace exit: .test_macro
130 *** de trace enter: .test_macro "some" "dummy" "arguments"
131 *** trace exit: .test_macro "some" "dummy" "arguments"
136 The entry and the exit of each macro call is displayed on the terminal
137 (standard output) \[em] together with the arguments (if any).
140 .\" --------------------------------------------------------------------
141 .SS "Nested macro calls"
154 > ' | groff -m trace >/dev/null
158 *** de trace enter: .parent
159 *** de trace enter: .child
160 *** trace exit: .child
161 *** trace exit: .parent
166 This shows that macro calls can be nested.
168 This powerful feature can help to tack down quite complex call stacks.
171 .\" --------------------------------------------------------------------
172 .SS "Activating with .mso"
187 > ' | groff >/dev/null
189 *** de trace enter: .after
190 *** trace exit: .after
195 Here, the tracing is activated within the document, not by a command
198 As tracing was not active when macro
200 was defined, no call of this macro is protocolled; on the other hand,
203 is fully protocolled.
206 .\" --------------------------------------------------------------------
208 .\" --------------------------------------------------------------------
214 request (and its cousins), macro arguments are expanded one level more.
216 This causes problems if an argument contains four backslashes or more
217 to prevent too early expansion of the backslash. For example, this
222 \&.foo \e\e\e\en[bar]
226 normally passes `\e\en[bar]' to macro `.foo', but with the redefined
228 request it passes `\en[bar]' instead.
231 The solution to this problem is to use groff's
233 escape which is an escape character not interpreted in copy mode, for
242 .\" --------------------------------------------------------------------
244 .\" --------------------------------------------------------------------
248 macros are kept in the file
251 .IR "tmac directory" ;
253 .BR groff_tmac (@MAN5EXT@)
257 .\" --------------------------------------------------------------------
259 .\" --------------------------------------------------------------------
263 A colon-separated list of additional tmac directories in which to
264 search for macro files; see
265 .BR groff_tmac (@MAN5EXT@)
269 .\" --------------------------------------------------------------------
271 .\" --------------------------------------------------------------------
273 Copyright (C) 2002, 2006, 2007, 2008 Free Software Foundation, Inc.
276 This document is distributed under the terms of the FDL (GNU Free
277 Documentation License) version 1.1 or later.
279 You should have received a copy of the FDL on your system, it is also
280 available on-line at the
281 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
286 This document is part of
288 the GNU roff distribution.
290 It was written by Bernd Warken.
293 .\" --------------------------------------------------------------------
295 .\" --------------------------------------------------------------------
298 .BR groff (@MAN1EXT@)
299 An overview of the groff system.
302 .BR troff (@MAN1EXT@)
303 For details on option
307 .BR groffer (@MAN1EXT@)
308 A viewer program for all kinds of roff documents.
311 .BR groff_tmac (@MAN5EXT@)
312 A general description of groff macro packages.
315 .BR groff (@MAN7EXT@)
316 A short reference for the groff formatting language.
319 A complete reference for all parts of the groff system is found in the