1groff_trace(7)         Miscellaneous Information Manual         groff_trace(7)
2
3
4

Name

6       groff_trace - macros for debugging GNU roff documents
7

Synopsis

9       groff -m trace [option ...] [file ...]
10

Description

12       trace  is  a macro package for the groff(7) document formatting system,
13       designed as an aid for debugging documents written in its language.  It
14       issues  a  message  to the standard error stream upon entry to and exit
15       from each macro call.  This can ease the process of isolating errors in
16       macro definitions.
17
18       Activate  the  package by specifying the command-line option “-m trace”
19       to the formatter program (often groff(1)).  You can achieve finer  con‐
20       trol  by  including  the macro file within the document; invoke the mso
21       request, as in “.mso trace.tmac”.  Only macros that are  defined  after
22       this  invocation  are  traced.   If the trace-full register is set to a
23       true value, as with the command-line option “-r trace-full=1”, register
24       and  string  assignments,  along  with  some other requests, are traced
25       also.  If another macro package should be traced as  well,  specify  it
26       after “-m trace” on the command line.
27
28       The  macro  file  trace.tmac is unusual because it does not contain any
29       macros to be called by a user.  Instead, groff's macro  definition  and
30       alteration  facilities  are  wrapped  such that they display diagnostic
31       messages.
32
33   Limitations
34       Because trace.tmac wraps the de request (and its cousins), macro  argu‐
35       ments are expanded one level more.  This causes problems if an argument
36       uses four or more backslashes to delay interpretation of an escape  se‐
37       quence.  For example, the macro call
38              .foo \\\\n[bar]
39       normally  passes  “\\n[bar]”  to macro “foo”, but with de redefined, it
40       passes “\n[bar]” instead.
41
42       The solution to this problem is to use groff's \E escape  sequence,  an
43       escape character that is not interpreted in copy mode.
44              .foo \En[bar]
45

Examples

47       We will illustrate trace.tmac using the shell's “here document” feature
48       to supply groff with a document on the standard input stream.  Since we
49       are  interested  only  in diagnostic messages appearing on the standard
50       error stream, we discard the formatted output by redirecting the  stan‐
51       dard output stream to /dev/null.
52
53   Observing nested macro calls
54       Macro  calls  can  be  nested,  even with themselves.  Tracing recurses
55       along with them; this feature can help to detangle complex call stacks.
56
57              $ cat <<EOF | groff -m trace > /dev/null
58              .de countdown
59              . nop \\$1
60              . nr count (\\$1 - 1)
61              . if \\n[count] .countdown \\n[count]
62              ..
63              .countdown 3
64              blastoff
65              EOF
66               *** .de countdown
67               *** de trace enter: .countdown "3"
68                *** de trace enter: .countdown "2"
69                 *** de trace enter: .countdown "1"
70                 *** trace exit: .countdown "1"
71                *** trace exit: .countdown "2"
72               *** trace exit: .countdown "3"
73
74   Tracing with the mso request
75       Now let us activate tracing within the document, not  with  a  command-
76       line  option.   We  might do this when using a macro package like ms or
77       mom, where we may not want to be distracted  by  traces  of  macros  we
78       didn't write.
79
80              $ cat <<EOF | groff -ms > /dev/null
81              .LP
82              This is my introductory paragraph.
83              .mso trace.tmac
84              .de Mymac
85              ..
86              .Mymac
87              .PP
88              Let us review the existing literature.
89              EOF
90               *** .de Mymac
91               *** de trace enter: .Mymac
92               *** trace exit: .Mymac
93
94       As  tracing  was  not yet active when the macros “LP” and “PP” were de‐
95       fined (by s.tmac), their calls were not traced; contrast with the macro
96       “Mymac”.
97

Files

99       /usr/share/groff/1.23.0/tmac/trace.tmac
100              implements the package.
101

Authors

103       trace.tmac  was  written  by James Clark.  This document was written by
104       Bernd Warken ⟨groff-bernd.warken-72@web.de⟩  and  G.  Branden  Robinson
105       ⟨g.branden.robinson@gmail.com⟩.
106

See also

108       Groff:  The  GNU Implementation of troff, by Trent A. Fisher and Werner
109       Lemberg, is the primary groff manual.  You can browse it  interactively
110       with “info groff”.
111
112       groff(1)
113              gives an overview of the groff document formatting system.
114
115       troff(1)
116              supplies details of the -m command-line option.
117
118       groff_tmac(5)
119              offers a survey of groff macro packages.
120
121       groff(7)
122              is a reference manual for the groff language.
123
124
125
126groff 1.23.0                    2 November 2023                 groff_trace(7)