1GROFF_TRACE(7) Miscellaneous Information Manual GROFF_TRACE(7)
2
6 groff_trace - groff macro package trace.tmac
7
9 groff -m trace [options ...] [files ...]
10
12 The trace macro package of groff(1) can be a valuable tool for debug‐
13 ging documents written in the roff formatting language. A call stack
14 trace is protocolled on standard error, this is, a diagnostic message
15 is emitted on entering and exiting of a macro call. This greatly eases
16 to track down an error in some macro.
17 This tracing process is activated by specifying the groff or troff com‐
19 mand line option -m trace. This works also with the groffer(1) viewer
20 program. A finer control can be obtained by including the macro file
21 within the document by the groff macro call .mso trace.tmac. Only
22 macros that are defined after this line are traced.
23 If command line option -r trace-full=1 is given (or if this register is
25 set in the document), number and string register assignments together
26 with some other requests are traced also.
27 If some other macro package should be traced as well it must be speci‐
29 fied after -m trace on the command line.
30 The macro file trace.tmac is unusual because it does not contain any
32 macros to be called by a user. Instead, the existing macro definition
33 and appending facilities are modified such that they display diagnostic
34 messages.
35
37 In the following examples, a roff fragment is fed into groff via stan‐
38 dard input. As we are only interested in the diagnostic messages
39 (standard error) on the terminal, the normal formatted output (standard
40 output) is redirected to the nirvana device /dev/null. The resulting
41 diagnostic messages are displayed directly below the corresponding
42 example.
43 Command line option
45 Example:
46 sh# echo '.
48 > .de test_macro
49 > ..
50 > .test_macro
51 > .test_macro some dummy arguments
52 > ' | groff -m trace > /dev/null
53 *** .de test_macro
55 *** de trace enter: .test_macro
56 *** trace exit: .test_macro
57 *** de trace enter: .test_macro "some" "dummy" "arguments"
58 *** trace exit: .test_macro "some" "dummy" "arguments"
59 The entry and the exit of each macro call is displayed on the terminal
61 (standard output) — together with the arguments (if any).
62 Nested macro calls
64 Example:
65 sh# echo '.
67 > .de child
68 > ..
69 > .de parent
70 > .child
71 > ..
72 > .parent
73 > ' | groff -m trace > /dev/null
74 *** .de child
76 *** .de parent
77 *** de trace enter: .parent
78 *** de trace enter: .child
79 *** trace exit: .child
80 *** trace exit: .parent
81 This shows that macro calls can be nested. This powerful feature can
83 help to tack down quite complex call stacks.
84 Activating with .mso
86 Example:
87 sh# echo '.
89 > .de before
90 > ..
91 > .mso trace.tmac
92 > .de after
93 > ..
94 > .before
95 > .after
96 > .before
97 > ' | groff > /dev/null
98 *** de trace enter: .after
100 *** trace exit: .after
101 Here, the tracing is activated within the document, not by a command
103 line option. As tracing was not active when macro before was defined,
104 no call of this macro is protocolled; on the other hand, the macro
105 after is fully protocolled.
106
108 Because trace.tmac wraps the .de request (and its cousins), macro argu‐
109 ments are expanded one level more. This causes problems if an argument
110 contains four backslashes or more to prevent too early expansion of the
111 backslash. For example, this macro call
112 .foo \\\\n[bar]
114 normally passes ‘\\n[bar]’ to macro ‘.foo’, but with the redefined .de
116 request it passes ‘\n[bar]’ instead.
117 The solution to this problem is to use groff's \E escape which is an
119 escape character not interpreted in copy mode, for example
120 .foo \En[bar]
122
124 The trace macros are kept in the file trace.tmac located in the tmac
125 directory; see groff_tmac(5) for details.
126
128 $GROFF_TMAC_PATH
129 A colon-separated list of additional tmac directories in which
130 to search for macro files; see groff_tmac(5) for details.
131
133 groff(1)
134 An overview of the groff system.
135 troff(1)
137 For details on option -m.
138 groffer(1)
140 A viewer program for all kinds of roff documents.
141 groff_tmac(5)
143 A general description of groff macro packages.
144 groff(7)
146 A short reference for the groff formatting language.
147 A complete reference for all parts of the groff system is found in the
149 groff info(1) file.
150
152 Copyright © 2002-2014 Free Software Foundation, Inc.
153 This file is part of groff, the GNU roff type-setting system.
155 Permission is granted to copy, distribute and/or modify this document
157 under the terms of the GNU Free Documentation License, Version 1.3 or
158 any later version published by the Free Software Foundation; with the
159 Invariant Sections being this .ig-section and AUTHOR, with no Front-
160 Cover Texts, and with no Back-Cover Texts.
161 A copy of the Free Documentation License is included as a file called
163 FDL in the main directory of the groff source package.
164
166 Written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
167Groff Version 1.22.3 4 November 2014 GROFF_TRACE(7)