groff_trace(7)

💖 NAME 💖

groff_trace — macros for debugging GNU roff documents 🐛✨

okay so bestie, this is the little macro package that helps you figure out why your roff document is being a whole mess. no cap, it's a lifesaver.

---

🌸 SYNOPSIS 🌸

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

---

✨ DESCRIPTION ✨

trace is a macro package for the groff(7) document formatting system, and honestly? it was literally designed as an aid for debugging documents written in its language. the way it works is iconic: it issues a message to the standard error stream upon entry to and exit from each macro call. that's it, that's the whole vibe — and it can ease the process of isolating errors in macro definitions, which, if you've ever been there, you know is giving nightmare fuel 😭

So how do you activate it? specify the command-line option -m trace to the formatter program (often groff(1)). easy.

But you can achieve finer control by including the macro file within the document — just invoke the mso request, as in .mso trace.tmac. 💅 heads up though: only macros that are defined after this invocation are traced. timing matters, bestie.

If the trace-full register is set to a true value, like with the command-line option -r trace-full=1, then register and string assignments, along with some other requests, are traced also. extra credit ✨

And if another macro package should be traced as well, specify it after -m trace on the command line. order is everything fr fr.

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. it's giving behind-the-scenes main character energy 👑

🦋 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. like, look at this macro call:

.foo \\\\n[bar]

normally that passes \\n[bar] to macro foo, but with de redefined, it passes \n[bar] instead. 💀 yeah. rude.

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. that's the one, that's the icon 🌟

---

🔥 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. clean. minimal. obsessed. 💜

⭐ 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. lowkey genius ngl.

$ 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. iykyk ✨

$ 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. see? timing. always timing. ⏰

---

👑 AUTHORS 👑

trace.tmac was written by James Clark. This document was written by Bernd Warken and G. Branden Robinson. absolute legends, all of them 🫶

---

💖 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. go read it bestie, it's the blueprint 📚

• groff(1) — gives an overview of the groff document formatting system.
• troff(1) — supplies details of the -m command-line option.
• groff_tmac(5) — offers a survey of groff macro packages.
• groff(7) — is a reference manual for the groff language.

---

and that's the whole page, bestie!! 💅✨ this beauty comes to you from groff 1.24.2, dated 2026-10-01 — go forth and debug, you've got this 🦋🎀⭐