. . --------------------------------------------------------------------
Legalize
--------------------------------------------------------------------
. 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. .. . --------------------------------------------------------------------
Setup
--------------------------------------------------------------------
. .do nr groff_trace_C \n[.C] .cp 0 . .mso www.tmac . . mso tty-char.tmac . ftr CR R . ftr CI I . ftr CB B .\} . . Global static variables for inter-macro communication
.rr @+Example_font . --------------------------------------------------------------------
setup for the macro definitions below
naming: namespace:category_macro.variable_name (experimental)
. --------------------------------------------------------------------
configuration of prompt for `.Shell_cmd'* macros
. automatically determine setup from the configuration above
.als @f trace:Shell_cmd_base.prompt_font\" .als @t trace:Shell_cmd.prompt_text\" .als @t+ trace:Shell_cmd+.prompt_text\" .nr @w \w'\*[trace:Shell_cmd.prompt]'\" .nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\" Full prompt width is maximum of texts plus 1m
.nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed .rr @w .rr @w+ . --------------------------------------------------------------------
Ignore all arguments like a comment, even after a .eo call.
.. .c -------------------------------------------------------------------- . ie (\\n[.$] < 3) \ . BI \\$@ . el \{\ . ds @tmp@ \\$1\f[]\\$2\f[] . shift 2 . Text \\*[@tmp@]\\$*\f[] . rm @tmp@ . \} .. .c -------------------------------------------------------------------- .c .Env_var (<env_var_name> [<punct>]) .c .c Display an environment variable, with optional punctuation. .c . nh . SM . Text \f[CB]\\$1\f[]\\$2 . hy .. .c -------------------------------------------------------------------- .c .Error (<text>...) .c .c Print error message to terminal and abort. .c . tm \\$* . ab .. .c -------------------------------------------------------------------- . if r@+Example_font \ . Error previous .Example was not terminated by a ./Example . nr @+Example_font \\n[.f] . nh . nf .c RS \\n[trace:Shell_cmd_base.prompt_width]u . ft CR .. .c -------------------------------------------------------------------- . if !r@+Example_font \ . Error no previous call to .Example . ft \\n[@+Example_font] .c RE . fi . hy . rr @+Example_font .. .c -------------------------------------------------------------------- . if (\\n[.$] <= 0) \ . Error \\$0 needs at least one argument. . ds @s .\f[B]\\$1\f[]\" . shift . if (\\n[.$] > 0) \ . as @s \~\f[I]\\$*\f[]\" . IP \\*[@s] . rm @s .. .c -------------------------------------------------------------------- . br . ns . Macdef \\$@ .. .c -------------------------------------------------------------------- .c .Shell_cmd (<CR> [<CI>] ...) .c .c A shell command line; display args alternating in fonts CR and CI. .c .c Examples: .c .Shell_cmd "groffer --dpi 100 file" .c result: `sh# groffer --dpi 100 file' .c with 'sh#' in font I, the rest in CR .c .c .Shell_cmd groffer\~--dpi\~100\~file .c result: the same as above .c .c .Shell_cmd "groffer --dpi=" value " file" .c result: sh# groffer --dpi=value file .c with `groffer --dpi=' and `file' in CR; `value' in CI .c .c .Shell_cmd groffer\~--dpi= value \~file .c result: the same as the previous example .c . trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@ .. .c -------------------------------------------------------------------- .c .Shell_cmd+ (<CR> [<CI>] ...) .c .c A continuation line for .Shell_cmd. .c . trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@ .. .c -------------------------------------------------------------------- .c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...]) .c .c A shell command line; display args alternating in fonts CR and CI. .c Internal, do not use directly. .c .c Globals: read-only register @.Shell_cmd_width .c . if (\\n[.$] <= 0) \ . return . nr @+font \\n[.f]\" . ds @prompt \\$1\" . ft CR . c gap between prompt and command . nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" . ds @res \\*[@prompt]\h'\\n[@+gap]u'\" . shift . ds @cf CR\" . while (\\n[.$] > 0) \{\ . as @res \\f[\\*[@cf]]\\$1\" . shift . ie '\\*[@cf]'CR' \ . ds @cf I\" . el \ . ds @cf CR\" . \} . br . ad l . nh . nf . Text \\*[@res]\" . fi . hy . ad . br . ft \\n[@+font] . rr @+font . rr @+gap . rm @cf . rm @res .. .c -------------------------------------------------------------------- .c .Text (<text>...) .c .c Treat the arguments as text, no matter how they look. .c . if (\\n[.$] == 0) \ . return . nop \)\\$*\) .. .c -------------------------------------------------------------------- .c .Topic ([<indent>]) .c .c A bulleted paragraph. .c . ie (\\n[.$] = 0) \ . .ds @indent 2m\" . el \ . .ds @indent \\$1\" . TP \\*[@indent] . Text \[bu] . rm @indent .. .c -------------------------------------------------------------------- .c .TP+ () .c .c Continuation line for .TP header. .c . br . ns . TP \\$1 .. .c -------------------------------------------------------------------- . ds @tmp@ `\f(CR\\$1\f[]' . shift . Text \\*[@tmp@]\\$* . rm @tmp@ .. .c -------------------------------------------------------------------- . ds @tmp@ \f(CB\\$1\f[] . shift 1 . Text \\*[@tmp@]\\$* . rm @tmp@ .. .c -------------------------------------------------------------------- . ds @tmp@ \f(CI\\$1\f[] . shift 1 . Text \\*[@tmp@]\\$* . rm @tmp@ .. .c -------------------------------------------------------------------- . ds @tmp@ \f(CB\\$1\f[] . shift 1 . Text .\\*[@tmp@]\\$* . rm @tmp@ .. .c -------------------------------------------------------------------- . ds @tmp@ \f[CB]\\$1\f[] . shift 1 . Text \[rs]\\*[@tmp@]\\$* . rm @tmp@ .. . . --------------------------------------------------------------------
SH SYNOPSIS
--------------------------------------------------------------------
. 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 (@MAN1EXT@) 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 "-m\~trace" . This works also with the groffer (@MAN1EXT@) viewer program. . A finer control can be obtained by including the macro file within the document by the groff macro call ".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 "-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
/dev/null . The resulting diagnostic messages are displayed directly below the
corresponding example.
.
.
--------------------------------------------------------------------
.Shell_cmd "echo '." .Shell_cmd+ ".de test_macro" .Shell_cmd+ ".." .Shell_cmd+ ".test_macro" .Shell_cmd+ ".test_macro some dummy arguments" .Shell_cmd+ "' | groff -m trace >/dev/null"
.Example *** 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).
.
.
--------------------------------------------------------------------
.Shell_cmd "echo '." .Shell_cmd+ ".de child" .Shell_cmd+ ".." .Shell_cmd+ ".de parent" .Shell_cmd+ ".child" .Shell_cmd+ ".." .Shell_cmd+ ".parent" .Shell_cmd+ "' | groff -m trace >/dev/null"
.Example *** 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.
.
.
--------------------------------------------------------------------
.Example *** 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 "tmac directory" ; see groff_tmac (@MAN5EXT@) for details. . . --------------------------------------------------------------------
.
.Env_var $GROFF_TMAC_PATH
A colon-separated list of additional tmac directories in which to
search for macro files; see
groff_tmac (@MAN5EXT@) 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 RL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . .
This document is part of
groff , the GNU roff distribution.
.
It was written by
.MTO bwarken@mayn.de "Bernd Warken".
.
.
--------------------------------------------------------------------
.
groff (@MAN1EXT@) An overview of the groff system. . .
troff (@MAN1EXT@) For details on option -m . . .
groffer (@MAN1EXT@) A viewer program for all kinds of roff documents. . .
groff_tmac (@MAN5EXT@) A general description of groff macro packages. . .
groff (@MAN7EXT@) A short reference for the groff formatting language. . .
A complete reference for all parts of the groff system is found in the
groff
info (1) file.
.
.cp \n[groff_trace_C]
.
Local Variables:
mode: nroff
End: