---
name: "groff_trace"
section: "7"
platform: "linux"
package: "groff"
version: "1.24.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/groff_trace"
---

# groff\_trace(7)

macros for debugging GNU roff documents

## 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)](/groff/7.md) 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 program (often [*groff*(1)](/groff/1.md)). 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 after 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 interpretation 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\]” instead.

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]
```

## Files

- */usr/share/groff/1.24.2/tmac/trace.tmac*

  implements the package.

## 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 feature 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 so when employing a macro package like *ms* or *mom*, to avoid distraction 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”.

## Authors

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

## 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)](/groff/1.md)

  gives an overview of the *groff* document formatting system.

- [*troff*(1)](/troff/1.md)

  supplies details of the **-m** command-line option.

- [*groff\_tmac*(5)](/groff_tmac/5.md)

  offers a survey of *groff* macro packages.

- [*groff*(7)](/groff/7.md)

  is a reference manual for the *groff* language.