{
    "mode": "man",
    "parameter": "groff_trace",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/groff_trace/7/json",
    "generated": "2026-10-04T13:31:58Z",
    "sections": {
        "Name": {
            "content": "grofftrace - macros for debugging GNU roff documents\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "groff -m trace [option ...] [file ...]\n",
            "subsections": []
        },
        "Description": {
            "content": "trace  is a macro package for the groff(7) document formatting system, designed as an aid for\ndebugging documents written in its language.  It issues  a  message  to  the  standard  error\nstream  upon  entry to and exit from each macro call.  This can ease the process of isolating\nerrors in macro definitions.\n\nActivate the package by specifying the command-line option “-m trace” to the  formatter  pro‐\ngram  (often groff(1)).  You can achieve finer control by including the macro file within the\ndocument; invoke the mso request, as in “.mso trace.tmac”.  Only macros that are defined  af‐\nter  this  invocation are traced.  If the trace-full register is set to a true value, as with\nthe command-line option “-r trace-full=1”, register and string assignments, along  with  some\nother  requests, are traced also.  If another macro package should be traced as well, specify\nit after “-m trace” on the command line.\n\nThe macro file trace.tmac is unusual because it does not contain any macros to be called by a\nuser.  Instead, groff's macro definition and alteration facilities are wrapped such that they\ndisplay diagnostic messages.\n",
            "subsections": [
                {
                    "name": "Limitations",
                    "content": "Because trace.tmac wraps the de request (and its cousins), macro arguments are  expanded  one\nlevel  more.   This causes problems if an argument uses four or more backslashes to delay in‐\nterpretation of an escape sequence.  For example, the macro call\n.foo \\\\\\\\n[bar]\nnormally passes “\\\\n[bar]” to macro “foo”, but with de redefined,  it  passes  “\\n[bar]”  in‐\nstead.\n\nThe  solution  to this problem is to use groff's \\E escape sequence, an escape character that\nis not interpreted in copy mode.\n.foo \\En[bar]\n"
                }
            ]
        },
        "Examples": {
            "content": "We will illustrate trace.tmac using the shell's “here document” feature to supply groff  with\na document on the standard input stream.  Since we are interested only in diagnostic messages\nappearing  on  the  standard error stream, we discard the formatted output by redirecting the\nstandard output stream to /dev/null.\n",
            "subsections": [
                {
                    "name": "Observing nested macro calls",
                    "content": "Macro calls can be nested, even with themselves.  Tracing recurses along with them; this fea‐\nture can help to detangle complex call stacks.\n\n$ cat <<EOF | groff -m trace > /dev/null\n.de countdown\n. nop \\\\$1\n. nr count (\\\\$1 - 1)\n. if \\\\n[count] .countdown \\\\n[count]\n..\n.countdown 3\nblastoff\nEOF\n* .de countdown\n* de trace enter: .countdown \"3\"\n* de trace enter: .countdown \"2\"\n* de trace enter: .countdown \"1\"\n* trace exit: .countdown \"1\"\n* trace exit: .countdown \"2\"\n* trace exit: .countdown \"3\"\n"
                },
                {
                    "name": "Tracing with the mso request",
                    "content": "Now let us activate tracing within the document, not with a command-line option.  We might do\nthis when using a macro package like ms or mom, where we may not want  to  be  distracted  by\ntraces of macros we didn't write.\n\n$ cat <<EOF | groff -ms > /dev/null\n.LP\nThis is my introductory paragraph.\n.mso trace.tmac\n.de Mymac\n..\n.Mymac\n.PP\nLet us review the existing literature.\nEOF\n* .de Mymac\n* de trace enter: .Mymac\n* trace exit: .Mymac\n\nAs  tracing  was not yet active when the macros “LP” and “PP” were defined (by s.tmac), their\ncalls were not traced; contrast with the macro “Mymac”.\n"
                }
            ]
        },
        "Files": {
            "content": "/usr/share/groff/1.23.0/tmac/trace.tmac\nimplements the package.\n",
            "subsections": []
        },
        "Authors": {
            "content": "trace.tmac was written by James Clark.  This document was  written  by  Bernd Warken  and  G.\nBranden Robinson.\n\nSee also\nGroff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary\ngroff manual.  You can browse it interactively with “info groff”.\n\ngroff(1)\ngives an overview of the groff document formatting system.\n\ntroff(1)\nsupplies details of the -m command-line option.\n\ngrofftmac(5)\noffers a survey of groff macro packages.\n\ngroff(7)\nis a reference manual for the groff language.\n\ngroff 1.23.0                                31 March 2024                             grofftrace(7)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}