# groff_trace - macros for debugging GNU roff documents - man(7) - [phpMan]

[_groff_trace_(7)](https://www.chedong.com/phpMan.php/man/grofftrace/7/markdown)                    Miscellaneous Information Manual                    [_groff_trace_(7)](https://www.chedong.com/phpMan.php/man/grofftrace/7/markdown)

## Name
       groff_trace - macros for debugging GNU _roff_ documents

## Synopsis
       **groff -m trace **[_option_ ...] [_file_ ...]

## Description
       _trace_  is a macro package for the [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown) document formatting system, designed as an aid for
       debugging documents written in its language.  It issues  a  message  to  the  standard  error
       stream  upon  entry to and exit from each macro call.  This can ease the process of isolating
       errors in macro definitions.

       Activate the package by specifying the command-line option “**-m trace**” to the  formatter  pro‐
       gram  (often [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)).  You can achieve finer control by including the macro file within the
       document; invoke the **mso **request, as in “**.mso trace.tmac**”.  Only macros that are defined  af‐
       ter  this  invocation are traced.  If the **trace-full **register is set to a true value, as with
       the command-line option “**-r trace-full=1**”, register and string assignments, along  with  some
       other  requests, are traced also.  If another macro package should be traced as well, specify
       it 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, _groff_'s macro definition and alteration facilities are wrapped such that they
       display diagnostic messages.

### Limitations
       Because _trace.tmac_ wraps the **de **request (and its cousins), macro arguments are  expanded  one
       level  more.   This causes problems if an argument uses four or more backslashes to delay in‐
       terpretation of an escape sequence.  For example, the macro call
              .foo \\\\n[bar]
       normally passes “\\n[bar]” to macro “foo”, but with **de **redefined,  it  passes  “\n[bar]”  in‐
       stead.

       The  solution  to this problem is to use _groff_'s **\E **escape sequence, an escape character that
       is not interpreted in copy mode.
              .foo \En[bar]

## Examples
       We will illustrate _trace.tmac_ using the shell's “here document” feature to supply _groff_  with
       a document on the standard input stream.  Since we are interested only in diagnostic messages
       appearing  on  the  standard error stream, we discard the formatted output by redirecting the
       standard output stream to _/dev/null_.

### Observing nested macro calls
       Macro calls can be nested, even with themselves.  Tracing recurses along with them; this fea‐
       ture can help to detangle complex call stacks.

              $ **cat <<EOF | groff -m trace > /dev/null**
              **.de countdown**
              **. nop \\$1**
              **. nr count (\\$1 - 1)**
              **. if \\n[count] .countdown \\n[count]**
              **..**
              **.countdown 3**
              **blastoff**
              **EOF**
               *** .de countdown
               *** de trace enter: .countdown "3"
                *** de trace enter: .countdown "2"
                 *** de trace enter: .countdown "1"
                 *** trace exit: .countdown "1"
                *** trace exit: .countdown "2"
               *** trace exit: .countdown "3"

### Tracing with the mso request
       Now let us activate tracing within the document, not with a command-line option.  We might do
       this when using a macro package like _ms_ or _mom_, where we may not want  to  be  distracted  by
       traces of macros we didn't write.

              $ **cat <<EOF | groff -ms > /dev/null**
              **.LP**
              **This is my introductory paragraph.**
              **.mso trace.tmac**
              **.de Mymac**
              **..**
              **.Mymac**
              **.PP**
              **Let us review the existing literature.**
              **EOF**
               *** .de Mymac
               *** de trace enter: .Mymac
               *** trace exit: .Mymac

       As  tracing  was not yet active when the macros “LP” and “PP” were defined (by _s.tmac_), their
       calls were not traced; contrast with the macro “Mymac”.

## Files
       _/usr/share/groff/1.23.0/tmac/trace.tmac_
              implements the package.

## Authors
       _trace.tmac_ was written by James Clark.  This document was  written  by  [Bernd Warken](mailto:<groff-bernd.warken-72@web.de>)  and  G.
       Branden Robinson.

**See also**
       _Groff:_ _The_ _GNU_ _Implementation_ _of_ _troff_, by Trent A. Fisher and Werner Lemberg, is the primary
       _groff_ manual.  You can browse it interactively with “info groff”.

       [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)
              gives an overview of the _groff_ document formatting system.

       [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)
              supplies details of the **-m **command-line option.

       [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown)
              offers a survey of _groff_ macro packages.

       [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)
              is a reference manual for the _groff_ language.

groff 1.23.0                                31 March 2024                             [_groff_trace_(7)](https://www.chedong.com/phpMan.php/man/grofftrace/7/markdown)