− groff macro package trace.tmac
groff −m trace
[options ...] [files
trace macro package of groff(1) can be a
valuable tool for debugging documents written in the roff
formatting language. A call stack trace is protocolled on
standard error, this is, a diagnostic message is emitted on
entering and exiting of a macro call. This greatly eases to
track down an error in some macro.
process is activated by specifying the groff or troff
command line option −m trace. This works
also with the groffer(1) viewer program. A finer
control can be obtained by including the macro file within
the document by the groff macro call
.mso trace.tmac. Only macros that are defined
after this line are traced.
If command line
option −r trace-full=1 is given (or if
this register is set in the document), number and string
register assignments together with some other requests are
If some other
macro package should be traced as well it must be specified
after −m trace on the command line.
The macro file
trace.tmac is unusual because it does not contain any
macros to be called by a user. Instead, the existing macro
definition and appending facilities are modified such that
they display diagnostic messages.
following examples, a roff fragment is fed into groff via
standard input. As we are only interested in the diagnostic
messages (standard error) on the terminal, the normal
formatted output (standard output) is redirected to the
nirvana device /dev/null. The resulting diagnostic
messages are displayed directly below the corresponding
> .de test_macro
> .test_macro some dummy arguments
> ' | groff −m trace > /dev/null
*** de trace enter: .test_macro
*** trace exit: .test_macro
*** de trace enter: .test_macro "some"
*** trace exit: .test_macro "some"
The entry and
the exit of each macro call is displayed on the terminal
(standard output) — together with the arguments (if
> .de child
> .de parent
> ' | groff −m trace > /dev/null
*** .de parent
*** de trace enter: .parent
*** de trace enter: .child
*** trace exit: .child
*** trace exit: .parent
This shows that
macro calls can be nested. This powerful feature can help to
tack down quite complex call stacks.
> .de before
> .mso trace.tmac
> .de after
> ' | groff > /dev/null
trace enter: .after
*** trace exit: .after
tracing is activated within the document, not by a command
line option. As tracing was not active when macro
before was defined, no call of this macro is
protocolled; on the other hand, the macro after is
trace.tmac wraps the .de request (and its
cousins), macro arguments are expanded one level more. This
causes problems if an argument contains four backslashes or
more to prevent too early expansion of the backslash. For
example, this macro call
’\\n[bar]’ to macro ’.foo’, but with
the redefined .de request it passes
The solution to
this problem is to use groff's \E escape which is an
escape character not interpreted in copy mode, for
trace macros are kept in the file trace.tmac
located in the tmac directory; see
groff_tmac(5) for details.
A colon-separated list of
additional tmac directories in which to search for macro
files; see groff_tmac(5) for details.
An overview of the groff
For details on option
A viewer program for all kinds
of roff documents.
A general description of groff
A short reference for the groff
reference for all parts of the groff system is found in the
groff info(1) file.
© 2002-2014 Free Software Foundation, Inc.
This file is
part of groff, the GNU roff type-setting system.
granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free
Software Foundation; with the Invariant Sections being this
.ig-section and AUTHOR, with no Front-Cover Texts, and with
no Back-Cover Texts.
A copy of the
Free Documentation License is included as a file called FDL
in the main directory of the groff source package.