1GROFF_TRACE(7) Miscellaneous Information Manual GROFF_TRACE(7)
2
3
4
6 groff_trace - groff macro package trace.tmac
7
9 groff -m trace [option ...] [input-file ...]
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
18 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
24 If the command-line option -r trace-full=1 is given (or if this regis‐
25 ter is set in the document), number and string register assignments to‐
26 gether with some other requests are traced also.
27
28 If some other macro package should be traced as well it must be speci‐
29 fied after -m trace on the command line.
30
31 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 ex‐
42 ample.
43
44 Command line option
45 Example:
46
47 sh# echo '.
48 > .de test_macro
49 > ..
50 > .test_macro
51 > .test_macro some dummy arguments
52 > ' | groff -m trace > /dev/null
53
54 *** .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
60 The entry and the exit of each macro call is displayed on the terminal
61 (standard output) — together with the arguments (if any).
62
63 Nested macro calls
64 Example:
65
66 sh# echo '.
67 > .de child
68 > ..
69 > .de parent
70 > .child
71 > ..
72 > .parent
73 > ' | groff -m trace > /dev/null
74
75 *** .de child
76 *** .de parent
77 *** de trace enter: .parent
78 *** de trace enter: .child
79 *** trace exit: .child
80 *** trace exit: .parent
81
82 This shows that macro calls can be nested. This powerful feature can
83 help to tack down quite complex call stacks.
84
85 Activating with .mso
86 Example:
87
88 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
99 *** de trace enter: .after
100 *** trace exit: .after
101
102 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 af‐
105 ter 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
113 .foo \\\\n[bar]
114
115 normally passes ‘\\n[bar]’ to macro ‘.foo’, but with the redefined .de
116 request it passes ‘\n[bar]’ instead.
117
118 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
121 .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 The trace macro packages was written by James Clark. This document was
134 written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
135
137 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
138 Lemberg, is the primary groff manual. You can browse it interactively
139 with “info groff”.
140
141 groff(1)
142 An overview of the groff system.
143
144 troff(1)
145 For details on option -m.
146
147 groffer(1)
148 A viewer program for all kinds of roff documents.
149
150 groff_tmac(5)
151 A general description of groff macro packages.
152
153 groff(7)
154 A short reference for the groff formatting language.
155
156
157
158groff 1.22.4 17 March 2021 GROFF_TRACE(7)