tmac/groff_trace.man

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