groff_trace

groff_trace - groff macro package trace.tmac

. . . groff_trace.7 File position: <groff-source>/tmac/groff_trace.man Last update: 14 July 2002 This file is part of groff, the GNU roff type-setting system. Copyright (C) 2002 Free Software Foundation, Inc. written by Bernd Warken <bwarken@mayn.de> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being this .ig-section and AUTHOR, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package. A copy of the GNU Free Documentation License is also available in this Debian package as /usr/share/doc/groff/copyright. . . . . . . . . . . . . groff -m trace [options\*[Ellipsis]] [files\*[Ellipsis]] . .

Elements in brackets denote optional arguments, and the ellipsis means that there can be any number of arguments of this kind. . .

. The trace macro package of groff(1) can be a valuable tool for debugging documents written in the roff formatting language. . A call stack trace is protocolled on standard error, that means, a diagnostic message is emitted on entering and exiting of a macro call. . This greatly eases to track down an error in some macro. . .

This tracing process is activated by specifying the groff or troff command line option R -m\~trace . This works also with the groffer(1) viewer program. . A finer control can be obtained by including the macro file within the document by the groff macro call R .mso\~trace.tmac . Only macros that are defined after this line are traced. . .

If some other macro package should be traced as well it must be specified after R -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, the existing macro definition and appending facilities are modified such that they display diagnostic messages. . .

.

In the following examples, a roff fragment is fed into groff via standard input. . As we are only interested in the diagnostic messages (standard error) on the terminal, the normal formatted output (standard output) is redirected into the nirvana device R /dev/null . The resulting diagnostic messages are displayed directly below the corresponding example. . .

Command line option

.

*** de trace enter: test_macro *** trace exit: test_macro *** de trace enter: test_macro "some" "dummy" "arguments" *** trace exit: test_macro "some" "dummy" "arguments" ./Example .

The entry and the exit of each macro call is displayed on the terminal (standard output) \[em] together with the arguments (if any). . .

Nested macro calls

.

*** de trace enter: parent *** de trace enter: child *** trace exit: child *** trace exit: parent ./Example .

This shows that macro calls can be nested. . This powerful feature can help to tack down quite complex call stacks. . .

Activating with .mso

.

*** de trace enter: after *** trace exit: after ./Example .

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 after is fully protocolled. . .

. The trace macros are kept in the file trace.tmac located in the R tmac directory ; see groff_tmac(5) for details. . .

.

. Copyright (C) 2002 Free Software Foundation, Inc. .

This document is distributed under the terms of the FDL (GNU Free Documentation License) version 1.1 or later. . You should have received a copy of the FDL on your system, it is also available on-line at the .

This document is part of R groff , the GNU roff distribution. . It was written by . .

.

groff(1)

troff(1)

groffer(1)

groff_tmac(5)

groff(7)

A complete reference for all parts of the groff system is found in the groff info(1) file. . .