{ "mode": "info", "parameter": "GROFF_TRACE", "section": "", "url": "https://www.chedong.com/phpMan.php/info/GROFF_TRACE/json", "generated": "2026-07-05T13:01:34Z", "synopsis": "groff -m trace [option ...] [input-file ...]", "sections": { "NAME": { "content": "grofftrace - groff macro package trace.tmac\n", "subsections": [] }, "SYNOPSIS": { "content": "groff -m trace [option ...] [input-file ...]\n", "subsections": [] }, "DESCRIPTION": { "content": "The trace macro package of groff(1) can be a valuable tool for debug-\nging documents written in the roff formatting language. A call stack\ntrace is protocolled on standard error, this is, a diagnostic message\nis emitted on entering and exiting of a macro call. This greatly eases\nto track down an error in some macro.\n\nThis tracing process is activated by specifying the groff or troff com-\nmand-line option -m trace. This works also with the groffer(1) viewer\nprogram. A finer control can be obtained by including the macro file\nwithin the document by the groff macro call .mso trace.tmac. Only\nmacros that are defined after this line are traced.\n\nIf the command-line option -r trace-full=1 is given (or if this regis-\nter is set in the document), number and string register assignments to-\ngether with some other requests are traced also.\n\nIf some other macro package should be traced as well it must be speci-\nfied after -m trace on the command line.\n\nThe macro file trace.tmac is unusual because it does not contain any\nmacros to be called by a user. Instead, the existing macro definition\nand appending facilities are modified such that they display diagnostic\nmessages.\n", "subsections": [] }, "EXAMPLES": { "content": "In the following examples, a roff fragment is fed into groff via stan-\ndard input. As we are only interested in the diagnostic messages\n(standard error) on the terminal, the normal formatted output (standard\noutput) is redirected to the nirvana device /dev/null. The resulting\ndiagnostic messages are displayed directly below the corresponding ex-\nample.\n\nCommand line option\nExample:\n\nsh# echo '.\n> .de testmacro\n> ..\n> .testmacro\n> .testmacro some dummy arguments\n> ' | groff -m trace > /dev/null\n\n* .de testmacro\n* de trace enter: .testmacro\n* trace exit: .testmacro\n* de trace enter: .testmacro \"some\" \"dummy\" \"arguments\"\n* trace exit: .testmacro \"some\" \"dummy\" \"arguments\"\n\nThe entry and the exit of each macro call is displayed on the terminal\n(standard output) -- together with the arguments (if any).\n\nNested macro calls\nExample:\n\nsh# echo '.\n> .de child\n> ..\n> .de parent\n> .child\n> ..\n> .parent\n> ' | groff -m trace > /dev/null\n\n* .de child\n* .de parent\n* de trace enter: .parent\n* de trace enter: .child\n* trace exit: .child\n* trace exit: .parent\n\nThis shows that macro calls can be nested. This powerful feature can\nhelp to tack down quite complex call stacks.\n\nActivating with .mso\nExample:\n\nsh# echo '.\n> .de before\n> ..\n> .mso trace.tmac\n> .de after\n> ..\n> .before\n> .after\n> .before\n> ' | groff > /dev/null\n\n* de trace enter: .after\n* trace exit: .after\n\nHere, the tracing is activated within the document, not by a command-\nline option. As tracing was not active when macro before was defined,\nno call of this macro is protocolled; on the other hand, the macro af-\nter is fully protocolled.\n", "subsections": [] }, "PROBLEMS": { "content": "Because trace.tmac wraps the .de request (and its cousins), macro argu-\nments are expanded one level more. This causes problems if an argument\ncontains four backslashes or more to prevent too early expansion of the\nbackslash. For example, this macro call\n\n.foo \\\\\\\\n[bar]\n\nnormally passes '\\\\n[bar]' to macro '.foo', but with the redefined .de\nrequest it passes '\\n[bar]' instead.\n\nThe solution to this problem is to use groff's \\E escape which is an\nescape character not interpreted in copy mode, for example\n\n.foo \\En[bar]\n", "subsections": [] }, "FILES": { "content": "The trace macros are kept in the file trace.tmac located in the tmac\ndirectory; see grofftmac(5) for details.\n", "subsections": [] }, "ENVIRONMENT": { "content": "GROFFTMACPATH\nA colon-separated list of additional tmac directories in which\nto search for macro files; see grofftmac(5) for details.\n", "subsections": [] }, "AUTHORS": { "content": "The trace macro packages was written by James Clark. This document was\nwritten by Bernd Warken .\n", "subsections": [] }, "SEE ALSO": { "content": "Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner\nLemberg, is the primary groff manual. You can browse it interactively\nwith \"info groff\".\n\ngroff(1)\nAn overview of the groff system.\n\ntroff(1)\nFor details on option -m.\n\ngroffer(1)\nA viewer program for all kinds of roff documents.\n\ngrofftmac(5)\nA general description of groff macro packages.\n\ngroff(7)\nA short reference for the groff formatting language.\n\ngroff 1.22.4 23 March 2022 GROFFTRACE(7)", "subsections": [] } }, "summary": "grofftrace - groff macro package trace.tmac", "flags": [], "examples": [ "In the following examples, a roff fragment is fed into groff via stan-", "dard 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 ex-", "ample.", "Command line option", "Example:", "sh# echo '.", "> .de testmacro", "> ..", "> .testmacro", "> .testmacro some dummy arguments", "> ' | groff -m trace > /dev/null", "* .de testmacro", "* de trace enter: .testmacro", "* trace exit: .testmacro", "* de trace enter: .testmacro \"some\" \"dummy\" \"arguments\"", "* trace exit: .testmacro \"some\" \"dummy\" \"arguments\"", "The entry and the exit of each macro call is displayed on the terminal", "(standard output) -- together with the arguments (if any).", "Nested macro calls", "Example:", "sh# echo '.", "> .de child", "> ..", "> .de parent", "> .child", "> ..", "> .parent", "> ' | groff -m trace > /dev/null", "* .de child", "* .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.", "Activating with .mso", "Example:", "sh# echo '.", "> .de before", "> ..", "> .mso trace.tmac", "> .de after", "> ..", "> .before", "> .after", "> .before", "> ' | groff > /dev/null", "* de trace enter: .after", "* trace exit: .after", "Here, the 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 af-", "ter is fully protocolled." ], "see_also": [ { "name": "groff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/groff/1/json" }, { "name": "troff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/troff/1/json" }, { "name": "groffer", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/groffer/1/json" }, { "name": "grofftmac", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/grofftmac/5/json" }, { "name": "groff", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/groff/7/json" } ] }