contrib/groff/tmac/groff_trace.man

   1 .ig
   2 groff_trace.7
   3
   4 File position: <groff-source>/tmac/groff_trace.man
   5
   6 Last update: 05 Jan 2009
   7
   8 This file is part of groff, the GNU roff type-setting system.
   9
  10 Copyright (C) 2002, 2006, 2007, 2008, 2009
  11   Free Software Foundation, Inc.
  12
  13 written by Bernd Warken.
  14
  15 Permission is granted to copy, distribute and/or modify this document
  16 under the terms of the GNU Free Documentation License, Version 1.3 or
  17 any later version published by the Free Software Foundation; with the
  18 Invariant Sections being this .ig-section and AUTHOR, with no
  19 Front-Cover Texts, and with no Back-Cover Texts.
  20
  21 A copy of the Free Documentation License is included as a file called
  22 FDL in the main directory of the groff source package.
  23 ..
  24 .
  25 .ds Ellipsis .\|.\|.\&\"
  26 .
  27 .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  28 .
  29 .SH NAME
  30 groff_trace \- groff macro package trace.tmac
  31 .
  32 .\" --------------------------------------------------------------------
  33 .SH SYNOPSIS
  34 .\" --------------------------------------------------------------------
  35 .
  36 .SY "groff \-m trace"
  37 .RI [ options
  38 .IR \*[Ellipsis] ]
  39 .RI [ files
  40 .IR \*[Ellipsis] ]
  41 .YS
  42 .
  43 .\" --------------------------------------------------------------------
  44 .SH DESCRIPTION
  45 .\" --------------------------------------------------------------------
  46 .
  47 The
  48 .I trace
  49 macro package of
  50 .BR groff (@MAN1EXT@)
  51 can be a valuable tool for debugging documents written in the roff
  52 formatting language.
  53 .
  54 A call stack trace is protocolled on standard error, this is, a
  55 diagnostic message is emitted on entering and exiting of a macro call.
  56 .
  57 This greatly eases to track down an error in some macro.
  58 .
  59 .
  60 .P
  61 This tracing process is activated by specifying the groff or troff
  62 command line option
  63 .BR \-m\ trace .
  64 This works also with the
  65 .BR groffer (@MAN1EXT@)
  66 viewer program.
  67 .
  68 A finer control can be obtained by including the macro file within the
  69 document by the groff macro call
  70 .BR .mso\ trace.tmac .
  71 Only macros that are defined after this line are traced.
  72 .
  73 .
  74 .P
  75 If command line option
  76 .B \-r\ trace-full=1
  77 is given (or if this register is set in the document), number and string
  78 register assignments together with some other requests are traced also.
  79 .
  80 .
  81 .P
  82 If some other macro package should be traced as well it must be specified
  83 after
  84 .B \-m\ trace
  85 on the command line.
  86 .
  87 .
  88 .P
  89 The macro file
  90 .B trace.tmac
  91 is unusual because it does not contain any macros to be called by a
  92 user.
  93 .
  94 Instead, the existing macro definition and appending facilities are
  95 modified such that they display diagnostic messages.
  96 .
  97 .
  98 .\" --------------------------------------------------------------------
  99 .SH EXAMPLES
 100 .\" --------------------------------------------------------------------
 101 .
 102 In the following examples, a roff fragment is fed into groff via
 103 standard input.
 104 .
 105 As we are only interested in the diagnostic messages (standard error)
 106 on the terminal, the normal formatted output (standard output) is
 107 redirected to the nirvana device
 108 .IR /dev/null .
 109 The resulting diagnostic messages are displayed directly below the
 110 corresponding example.
 111 .
 112 .
 113 .\" --------------------------------------------------------------------
 114 .SS "Command line option"
 115 Example:
 116 .
 117 .RS
 118 .P
 119 .EX
 120 \fIsh#\fP echo '.
 121 > .de test_macro
 122 > ..
 123 > .test_macro
 124 > .test_macro some dummy arguments
 125 > ' | groff -m trace >/dev/null
 126
 127 *** .de test_macro
 128 *** de trace enter: .test_macro
 129 *** trace exit: .test_macro
 130 *** de trace enter: .test_macro "some" "dummy" "arguments"
 131 *** trace exit: .test_macro "some" "dummy" "arguments"
 132 .EE
 133 .RE
 134 .
 135 .P
 136 The entry and the exit of each macro call is displayed on the terminal
 137 (standard output) \[em] together with the arguments (if any).
 138 .
 139 .
 140 .\" --------------------------------------------------------------------
 141 .SS "Nested macro calls"
 142 Example:
 143 .
 144 .RS
 145 .P
 146 .EX
 147 \fIsh#\fP echo '.
 148 > .de child
 149 > ..
 150 > .de parent
 151 > .child
 152 > ..
 153 > .parent
 154 > ' | groff -m trace >/dev/null
 155
 156 *** .de child
 157 *** .de parent
 158 *** de trace enter: .parent
 159  *** de trace enter: .child
 160  *** trace exit: .child
 161 *** trace exit: .parent
 162 .EE
 163 .RE
 164 .
 165 .P
 166 This shows that macro calls can be nested.
 167 .
 168 This powerful feature can help to tack down quite complex call stacks.
 169 .
 170 .
 171 .\" --------------------------------------------------------------------
 172 .SS "Activating with .mso"
 173 Example:
 174 .
 175 .RS
 176 .P
 177 .EX
 178 \fIsh#\fP echo '.
 179 > .de before
 180 > ..
 181 > .mso trace.tmac
 182 > .de after
 183 > ..
 184 > .before
 185 > .after
 186 > .before
 187 >  ' | groff >/dev/null
 188
 189 *** de trace enter: .after
 190 *** trace exit: .after
 191 .EE
 192 .RE
 193 .
 194 .P
 195 Here, the tracing is activated within the document, not by a command
 196 line option.
 197 .
 198 As tracing was not active when macro
 199 .I before
 200 was defined, no call of this macro is protocolled; on the other hand,
 201 the macro
 202 .I after
 203 is fully protocolled.
 204 .
 205 .
 206 .\" --------------------------------------------------------------------
 207 .SH PROBLEMS
 208 .\" --------------------------------------------------------------------
 209 .
 210 Because
 211 .B trace.tmac
 212 wraps the
 213 .B .de
 214 request (and its cousins), macro arguments are expanded one level more.
 215 .
 216 This causes problems if an argument contains four backslashes or more
 217 to prevent too early expansion of the backslash.  For example, this
 218 macro call
 219 .
 220 .IP
 221 .EX
 222 \&.foo \e\e\e\en[bar]
 223 .EE
 224 .
 225 .P
 226 normally passes `\e\en[bar]' to macro `.foo', but with the redefined
 227 .B .de
 228 request it passes `\en[bar]' instead.
 229 .
 230 .P
 231 The solution to this problem is to use groff's
 232 .B \eE
 233 escape which is an escape character not interpreted in copy mode, for
 234 example
 235 .
 236 .IP
 237 .EX
 238 \&.foo \eEn[bar]
 239 .EE
 240 .
 241 .
 242 .\" --------------------------------------------------------------------
 243 .SH FILES
 244 .\" --------------------------------------------------------------------
 245 .
 246 The
 247 .I trace
 248 macros are kept in the file
 249 .B trace.tmac
 250 located in the
 251 .IR "tmac directory" ;
 252 see
 253 .BR groff_tmac (@MAN5EXT@)
 254 for details.
 255 .
 256 .
 257 .\" --------------------------------------------------------------------
 258 .SH ENVIRONMENT
 259 .\" --------------------------------------------------------------------
 260 .
 261 .TP
 262 .B $GROFF_TMAC_PATH
 263 A colon-separated list of additional tmac directories in which to
 264 search for macro files; see
 265 .BR groff_tmac (@MAN5EXT@)
 266 for details.
 267 .
 268 .
 269 .\" --------------------------------------------------------------------
 270 .SH AUTHOR
 271 .\" --------------------------------------------------------------------
 272 .
 273 Copyright (C) 2002, 2006, 2007, 2008 Free Software Foundation, Inc.
 274 .
 275 .P
 276 This document is distributed under the terms of the FDL (GNU Free
 277 Documentation License) version 1.1 or later.
 278 .
 279 You should have received a copy of the FDL on your system, it is also
 280 available on-line at the
 281 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
 282 GNU copyleft site
 283 .UE .
 284 .
 285 .P
 286 This document is part of
 287 .IR groff ,
 288 the GNU roff distribution.
 289 .
 290 It was written by Bernd Warken.
 291 .
 292 .
 293 .\" --------------------------------------------------------------------
 294 .SH "SEE ALSO"
 295 .\" --------------------------------------------------------------------
 296 .
 297 .TP
 298 .BR groff (@MAN1EXT@)
 299 An overview of the groff system.
 300 .
 301 .TP
 302 .BR troff (@MAN1EXT@)
 303 For details on option
 304 .BR \-m .
 305 .
 306 .TP
 307 .BR groffer (@MAN1EXT@)
 308 A viewer program for all kinds of roff documents.
 309 .
 310 .TP
 311 .BR groff_tmac (@MAN5EXT@)
 312 A general description of groff macro packages.
 313 .
 314 .TP
 315 .BR groff (@MAN7EXT@)
 316 A short reference for the groff formatting language.
 317 .
 318 .P
 319 A complete reference for all parts of the groff system is found in the
 320 groff
 321 .BR info (1)
 322 file.
 323 .
 324 .\" Local Variables:
 325 .\" mode: nroff
 326 .\" End: