1 .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
3 groff_trace \- groff macro package trace.tmac
6 .\" File position: <groff-source>/tmac/groff_trace.man
9 .\" --------------------------------------------------------------------
11 .\" --------------------------------------------------------------------
14 Copyright \[co] 2002-2014 Free Software Foundation, Inc.
16 This file is part of groff, the GNU roff type-setting system.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.3 or
20 any later version published by the Free Software Foundation; with the
21 Invariant Sections being this .ig-section and AUTHOR, with no
22 Front-Cover Texts, and with no Back-Cover Texts.
24 A copy of the Free Documentation License is included as a file called
25 FDL in the main directory of the groff source package.
30 .MT groff-bernd.warken-72@web.de
35 .ds Ellipsis .\|.\|.\&\"
38 .\" --------------------------------------------------------------------
40 .\" --------------------------------------------------------------------
50 .\" --------------------------------------------------------------------
52 .\" --------------------------------------------------------------------
58 can be a valuable tool for debugging documents written in the roff
61 A call stack trace is protocolled on standard error, this is, a
62 diagnostic message is emitted on entering and exiting of a macro call.
64 This greatly eases to track down an error in some macro.
68 This tracing process is activated by specifying the groff or troff
72 This works also with the
73 .BR groffer (@MAN1EXT@)
76 A finer control can be obtained by including the macro file within the
77 document by the groff macro call
78 .BR .mso\ trace.tmac .
80 Only macros that are defined after this line are traced.
84 If command line option
86 is given (or if this register is set in the document), number and
87 string register assignments together with some other requests are
92 If some other macro package should be traced as well it must be
101 is unusual because it does not contain any macros to be called by a
104 Instead, the existing macro definition and appending facilities are
105 modified such that they display diagnostic messages.
108 .\" --------------------------------------------------------------------
110 .\" --------------------------------------------------------------------
112 In the following examples, a roff fragment is fed into groff via
115 As we are only interested in the diagnostic messages (standard error)
116 on the terminal, the normal formatted output (standard output) is
117 redirected to the nirvana device
120 The resulting diagnostic messages are displayed directly below the
121 corresponding example.
124 .\" --------------------------------------------------------------------
125 .SS "Command line option"
131 \fIsh#\fP echo \[aq].
135 > .test_macro some dummy arguments
136 > \[aq] | groff \-m trace > /dev/null
139 *** de trace enter: .test_macro
140 *** trace exit: .test_macro
141 *** de trace enter: .test_macro "some" "dummy" "arguments"
142 *** trace exit: .test_macro "some" "dummy" "arguments"
147 The entry and the exit of each macro call is displayed on the terminal
148 (standard output) \[em] together with the arguments (if any).
151 .\" --------------------------------------------------------------------
152 .SS "Nested macro calls"
158 \fIsh#\fP echo \[aq].
165 > \[aq] | groff \-m trace > /dev/null
169 *** de trace enter: .parent
170 *** de trace enter: .child
171 *** trace exit: .child
172 *** trace exit: .parent
177 This shows that macro calls can be nested.
179 This powerful feature can help to tack down quite complex call stacks.
182 .\" --------------------------------------------------------------------
183 .SS "Activating with .mso"
189 \fIsh#\fP echo \[aq].
198 > \[aq] | groff > /dev/null
200 *** de trace enter: .after
201 *** trace exit: .after
206 Here, the tracing is activated within the document, not by a command
209 As tracing was not active when macro
211 was defined, no call of this macro is protocolled; on the other hand,
214 is fully protocolled.
217 .\" --------------------------------------------------------------------
219 .\" --------------------------------------------------------------------
225 request (and its cousins), macro arguments are expanded one level more.
227 This causes problems if an argument contains four backslashes or more
228 to prevent too early expansion of the backslash.
230 For example, this macro call
234 \&.foo \e\e\e\en[bar]
239 normally passes \[oq]\e\en[bar]\[cq] to macro \[oq].foo\[cq], but with
242 request it passes \[oq]\en[bar]\[cq] instead.
246 The solution to this problem is to use groff\[aq]s
248 escape which is an escape character not interpreted in copy mode, for
257 .\" --------------------------------------------------------------------
259 .\" --------------------------------------------------------------------
263 macros are kept in the file
266 .IR "tmac directory" ;
268 .BR groff_tmac (@MAN5EXT@)
272 .\" --------------------------------------------------------------------
274 .\" --------------------------------------------------------------------
278 A colon-separated list of additional tmac directories in which to
279 search for macro files; see
280 .BR groff_tmac (@MAN5EXT@)
284 .\" --------------------------------------------------------------------
286 .\" --------------------------------------------------------------------
289 .BR groff (@MAN1EXT@)
290 An overview of the groff system.
293 .BR troff (@MAN1EXT@)
294 For details on option
298 .BR groffer (@MAN1EXT@)
299 A viewer program for all kinds of roff documents.
302 .BR groff_tmac (@MAN5EXT@)
303 A general description of groff macro packages.
306 .BR groff (@MAN7EXT@)
307 A short reference for the groff formatting language.
310 A complete reference for all parts of the groff system is found in the
316 .\" --------------------------------------------------------------------
318 .\" --------------------------------------------------------------------
320 .\" --------------------------------------------------------------------
322 .\" --------------------------------------------------------------------