contrib/groff/tmac/groff_trace.man

   1 .
   2 .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
   3 .SH NAME
   4 groff_trace \- groff macro package trace.tmac
   5 .SH SYNOPSIS
   6 .\" The .SH was moved to this place to make `apropos' happy.
   7 .
   8 .
   9 .\" --------------------------------------------------------------------
  10 .\" Legalize
  11 .\" --------------------------------------------------------------------
  12 .
  13 .ig
  14 groff_trace.7
  15
  16 File position: <groff-source>/tmac/groff_trace.man
  17
  18 Last update: 14 July 2002
  19
  20 This file is part of groff, the GNU roff type-setting system.
  21
  22 Copyright (C) 2002 Free Software Foundation, Inc.
  23 written by Bernd Warken <bwarken@mayn.de>
  24
  25 Permission is granted to copy, distribute and/or modify this document
  26 under the terms of the GNU Free Documentation License, Version 1.1 or
  27 any later version published by the Free Software Foundation; with the
  28 Invariant Sections being this .ig-section and AUTHOR, with no
  29 Front-Cover Texts, and with no Back-Cover Texts.
  30
  31 A copy of the Free Documentation License is included as a file called
  32 FDL in the main directory of the groff source package.
  33 ..
  34 .
  35 .\" --------------------------------------------------------------------
  36 .\" Setup
  37 .\" --------------------------------------------------------------------
  38 .
  39 .mso www.tmac
  40 .
  41 .if n \{\
  42 .  mso tty-char.tmac
  43 .  ftr CR R
  44 .  ftr CI I
  45 .  ftr CB B
  46 .\}
  47 .
  48 .ds Ellipsis .\|.\|.\&\"
  49 .
  50 .\" Global static variables for inter-macro communication
  51 .rr @+Example_font
  52 .
  53 .\" --------------------------------------------------------------------
  54 .\" setup for the macro definitions below
  55 .\"
  56 .\" naming:  namespace:category_macro.variable_name  (experimental)
  57 .
  58 .\" --------------------------------------------------------------------
  59 .\" configuration of prompt for `.Shell_cmd'* macros
  60 .ds trace:Shell_cmd.prompt_text sh#\"    prompt for shell commands
  61 .ds trace:Shell_cmd+.prompt_text >\"     prompt on continuation lines
  62 .ds trace:Shell_cmd_base.prompt_font I\" font for prompts
  63 .
  64 .\" automatically determine setup from the configuration above
  65 .als @f trace:Shell_cmd_base.prompt_font\"
  66 .als @t trace:Shell_cmd.prompt_text\"
  67 .als @t+ trace:Shell_cmd+.prompt_text\"
  68 .ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\"            needed
  69 .ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\"          needed
  70 .nr @w \w'\*[trace:Shell_cmd.prompt]'\"
  71 .nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\"
  72 .ft \*[@f]
  73 .\" Full prompt width is maximum of texts plus 1m
  74 .nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
  75 .ft
  76 .rm @f
  77 .rm @f+
  78 .rm @t
  79 .rm @t+
  80 .rr @w
  81 .rr @w+
  82 .
  83 .\"--------------------------------------------------------------------
  84 .\" Ignore all arguments like a comment, even after a .eo call.
  85 .de c
  86 ..
  87 .c --------------------------------------------------------------------
  88 .de BIR
  89 .  ie (\\n[.$] < 3) \
  90 .    BI \\$@
  91 .  el \{\
  92 .    ds @tmp@ \fB\\$1\f[]\fI\\$2\f[]
  93 .    shift 2
  94 .    Text \\*[@tmp@]\fR\\$*\f[]
  95 .    rm @tmp@
  96 .  \}
  97 ..
  98 .c --------------------------------------------------------------------
  99 .c .Env_var  (<env_var_name> [<punct>])
 100 .c
 101 .c Display an environment variable, with optional punctuation.
 102 .c
 103 .de Env_var
 104 .  nh
 105 .  SM
 106 .  Text \f[CB]\\$1\f[]\\$2
 107 .  hy
 108 ..
 109 .c --------------------------------------------------------------------
 110 .c .Error  (<text>...)
 111 .c
 112 .c Print error message to terminal and abort.
 113 .c
 114 .de Error
 115 .  tm \\$*
 116 .  ab
 117 ..
 118 .c --------------------------------------------------------------------
 119 .de Example
 120 .  if r@+Example_font \
 121 .    Error previous .Example was not terminated by a ./Example
 122 .  nr @+Example_font \\n[.f]
 123 .  nh
 124 .  nf
 125 .c  RS \\n[trace:Shell_cmd_base.prompt_width]u
 126 .  ft CR
 127 ..
 128 .c --------------------------------------------------------------------
 129 .de /Example
 130 .  if !r@+Example_font \
 131 .    Error no previous call to .Example
 132 .  ft \\n[@+Example_font]
 133 .c  RE
 134 .  fi
 135 .  hy
 136 .  rr @+Example_font
 137 ..
 138 .c --------------------------------------------------------------------
 139 .de Macdef
 140 .  if (\\n[.$] <= 0) \
 141 .    Error \\$0 needs at least one argument.
 142 .  ds @s .\f[B]\\$1\f[]\"
 143 .  shift
 144 .  if (\\n[.$] > 0) \
 145 .    as @s \~\f[I]\\$*\f[]\"
 146 .  IP \\*[@s]
 147 .  rm @s
 148 ..
 149 .c --------------------------------------------------------------------
 150 .de Macdef+
 151 .  br
 152 .  ns
 153 .  Macdef \\$@
 154 ..
 155 .c --------------------------------------------------------------------
 156 .c .Shell_cmd  (<CR> [<CI>] ...)
 157 .c
 158 .c A shell command line; display args alternating in fonts CR and CI.
 159 .c
 160 .c Examples:
 161 .c   .Shell_cmd "groffer --dpi 100 file"
 162 .c     result: `sh#  groffer --dpi 100 file'
 163 .c             with 'sh#' in font I, the rest in CR
 164 .c
 165 .c   .Shell_cmd groffer\~--dpi\~100\~file
 166 .c     result: the same as above
 167 .c
 168 .c   .Shell_cmd "groffer --dpi=" value " file"
 169 .c     result: sh#  groffer --dpi=value file
 170 .c             with `groffer --dpi=' and `file' in CR; `value' in CI
 171 .c
 172 .c   .Shell_cmd groffer\~--dpi= value \~file
 173 .c     result: the same as the previous example
 174 .c
 175 .de Shell_cmd
 176 .  trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@
 177 ..
 178 .c --------------------------------------------------------------------
 179 .c .Shell_cmd+  (<CR> [<CI>] ...)
 180 .c
 181 .c A continuation line for .Shell_cmd.
 182 .c
 183 .de Shell_cmd+
 184 .  trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@
 185 ..
 186 .c --------------------------------------------------------------------
 187 .c .Shell_cmd_base  (<prompt> [<CR> [<CI>] ...])
 188 .c
 189 .c A shell command line; display args alternating in fonts CR and CI.
 190 .c Internal, do not use directly.
 191 .c
 192 .c Globals: read-only register @.Shell_cmd_width
 193 .c
 194 .de trace:Shell_cmd_base
 195 .  if (\\n[.$] <= 0) \
 196 .    return
 197 .  nr @+font \\n[.f]\"
 198 .  ds @prompt \\$1\"
 199 .  ft CR
 200 .  c gap between prompt and command
 201 .  nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
 202 .  ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
 203 .  shift
 204 .  ds @cf CR\"
 205 .  while (\\n[.$] > 0) \{\
 206 .    as @res \\f[\\*[@cf]]\\$1\"
 207 .    shift
 208 .    ie '\\*[@cf]'CR' \
 209 .      ds @cf I\"
 210 .    el \
 211 .      ds @cf CR\"
 212 .  \}
 213 .  br
 214 .  ad l
 215 .  nh
 216 .  nf
 217 .  Text \\*[@res]\"
 218 .  fi
 219 .  hy
 220 .  ad
 221 .  br
 222 .  ft \\n[@+font]
 223 .  rr @+font
 224 .  rr @+gap
 225 .  rm @cf
 226 .  rm @res
 227 ..
 228 .c --------------------------------------------------------------------
 229 .c .Text  (<text>...)
 230 .c
 231 .c Treat the arguments as text, no matter how they look.
 232 .c
 233 .de Text
 234 .  if (\\n[.$] == 0) \
 235 .    return
 236 .  nop \)\\$*\)
 237 ..
 238 .c --------------------------------------------------------------------
 239 .c .Topic  ([<indent>])
 240 .c
 241 .c A bulleted paragraph.
 242 .c
 243 .de Topic
 244 .  ie (\\n[.$] = 0) \
 245 .    .ds @indent 2m\"
 246 .  el \
 247 .    .ds @indent \\$1\"
 248 .  TP \\*[@indent]
 249 .  Text \[bu]
 250 .  rm @indent
 251 ..
 252 .c --------------------------------------------------------------------
 253 .c .TP+  ()
 254 .c
 255 .c Continuation line for .TP header.
 256 .c
 257 .de TP+
 258 .  br
 259 .  ns
 260 .  TP \\$1
 261 ..
 262 .c --------------------------------------------------------------------
 263 .de 'char
 264 .  ds @tmp@ `\f(CR\\$1\f[]'
 265 .  shift
 266 .  Text \\*[@tmp@]\\$*
 267 .  rm @tmp@
 268 ..
 269 .c --------------------------------------------------------------------
 270 .de option
 271 .  ds @tmp@ \f(CB\\$1\f[]
 272 .  shift 1
 273 .  Text \\*[@tmp@]\\$*
 274 .  rm @tmp@
 275 ..
 276 .c --------------------------------------------------------------------
 277 .de argument
 278 .  ds @tmp@ \f(CI\\$1\f[]
 279 .  shift 1
 280 .  Text \\*[@tmp@]\\$*
 281 .  rm @tmp@
 282 ..
 283 .c --------------------------------------------------------------------
 284 .de request
 285 .  ds @tmp@ \f(CB\\$1\f[]
 286 .  shift 1
 287 .  Text .\\*[@tmp@]\\$*
 288 .  rm @tmp@
 289 ..
 290 .c --------------------------------------------------------------------
 291 .de escape
 292 .  ds @tmp@ \f[CB]\\$1\f[]
 293 .  shift 1
 294 .  Text \[rs]\\*[@tmp@]\\$*
 295 .  rm @tmp@
 296 ..
 297 .
 298 .
 299 .\" --------------------------------------------------------------------
 300 .\" SH SYNOPSIS
 301 .\" --------------------------------------------------------------------
 302 .
 303 .B groff -m trace
 304 .RI [ options\*[Ellipsis] ]
 305 .RI [ files\*[Ellipsis] ]
 306 .
 307 .
 308 .P
 309 Elements in brackets denote optional arguments, and the ellipsis means
 310 that there can be any number of arguments of this kind.
 311 .
 312 .
 313 .\" --------------------------------------------------------------------
 314 .SH DESCRIPTION
 315 .\" --------------------------------------------------------------------
 316 .
 317 The
 318 .I trace
 319 macro package of
 320 .BR groff (@MAN1EXT@)
 321 can be a valuable tool for debugging documents written in the roff
 322 formatting language.
 323 .
 324 A call stack trace is protocolled on standard error, that means, a
 325 diagnostic message is emitted on entering and exiting of a macro call.
 326 .
 327 This greatly eases to track down an error in some macro.
 328 .
 329 .
 330 .P
 331 This tracing process is activated by specifying the groff or troff
 332 command line option
 333 .BR "-m\~trace" .
 334 This works also with the
 335 .BR groffer (@MAN1EXT@)
 336 viewer program.
 337 .
 338 A finer control can be obtained by including the macro file within the
 339 document by the groff macro call
 340 .BR ".mso\~trace.tmac" .
 341 Only macros that are defined after this line are traced.
 342 .
 343 .
 344 .P
 345 If some other macro package should be traced as well it must be specified
 346 after
 347 .BR "-m\~trace"
 348 on the command line.
 349 .
 350 .
 351 .P
 352 The macro file
 353 .B trace.tmac
 354 is unusual because it does not contain any macros to be called by a
 355 user.
 356 .
 357 Instead, the existing macro definition and appending facilities are
 358 modified such that they display diagnostic messages.
 359 .
 360 .
 361 .\" --------------------------------------------------------------------
 362 .SH EXAMPLES
 363 .\" --------------------------------------------------------------------
 364 .
 365 .P
 366 In the following examples, a roff fragment is fed into groff via
 367 standard input.
 368 .
 369 As we are only interested in the diagnostic messages (standard error)
 370 on the terminal, the normal formatted output (standard output) is
 371 redirected into the nirvana device
 372 .IR /dev/null .
 373 The resulting diagnostic messages are displayed directly below the
 374 corresponding example.
 375 .
 376 .
 377 .\" --------------------------------------------------------------------
 378 .SS "Command line option"
 379 .
 380 .P
 381 .Shell_cmd "echo '."
 382 .Shell_cmd+ ".de test_macro"
 383 .Shell_cmd+ ".."
 384 .Shell_cmd+ ".test_macro"
 385 .Shell_cmd+ ".test_macro some dummy arguments"
 386 .Shell_cmd+ "' | groff -m trace >/dev/null"
 387 .P
 388 .Example
 389 *** de trace enter: test_macro
 390 *** trace exit: test_macro
 391 *** de trace enter: test_macro "some" "dummy" "arguments"
 392 *** trace exit: test_macro "some" "dummy" "arguments"
 393 ./Example
 394 .
 395 .P
 396 The entry and the exit of each macro call is displayed on the terminal
 397 (standard output) \[em] together with the arguments (if any).
 398 .
 399 .
 400 .\" --------------------------------------------------------------------
 401 .SS "Nested macro calls"
 402 .
 403 .P
 404 .Shell_cmd "echo '."
 405 .Shell_cmd+ ".de child"
 406 .Shell_cmd+ ".."
 407 .Shell_cmd+ ".de parent"
 408 .Shell_cmd+ ".child"
 409 .Shell_cmd+ ".."
 410 .Shell_cmd+ ".parent"
 411 .Shell_cmd+ "' | groff -m trace >/dev/null"
 412 .P
 413 .Example
 414 *** de trace enter: parent
 415 *** de trace enter: child
 416 *** trace exit: child
 417 *** trace exit: parent
 418 ./Example
 419 .
 420 .P
 421 This shows that macro calls can be nested.
 422 .
 423 This powerful feature can help to tack down quite complex call stacks.
 424 .
 425 .
 426 .\" --------------------------------------------------------------------
 427 .SS "Activating with .mso"
 428 .
 429 .Shell_cmd "echo '."
 430 .Shell_cmd+ ".de before"
 431 .Shell_cmd+ ..
 432 .Shell_cmd+ ".mso trace.tmac"
 433 .Shell_cmd+ ".de after"
 434 .Shell_cmd+ ..
 435 .Shell_cmd+ .before
 436 .Shell_cmd+ .after
 437 .Shell_cmd+ .before
 438 .Shell_cmd+ "' | groff >/dev/null"
 439 .P
 440 .Example
 441 *** de trace enter: after
 442 *** trace exit: after
 443 ./Example
 444 .
 445 .P
 446 Here, the tracing is activated within the document, not by a command
 447 line option.
 448 .
 449 As tracing was not active when macro
 450 .I before
 451 was defined, no call of this macro is protocolled; on the other hand,
 452 the macro
 453 .I after
 454 is fully protocolled.
 455 .
 456 .
 457 .\" --------------------------------------------------------------------
 458 .SH FILES
 459 .\" --------------------------------------------------------------------
 460 .
 461 The
 462 .I trace
 463 macros are kept in the file
 464 .B trace.tmac
 465 located in the
 466 .IR "tmac directory" ;
 467 see
 468 .BR groff_tmac (@MAN5EXT@)
 469 for details.
 470 .
 471 .
 472 .\" --------------------------------------------------------------------
 473 .SH ENVIRONMENT
 474 .\" --------------------------------------------------------------------
 475 .
 476 .TP
 477 .Env_var $GROFF_TMAC_PATH
 478 A colon-separated list of additional tmac directories in which to
 479 search for macro files; see
 480 .BR groff_tmac (@MAN5EXT@)
 481 for details.
 482 .
 483 .
 484 .\" --------------------------------------------------------------------
 485 .SH AUTHOR
 486 .\" --------------------------------------------------------------------
 487 .
 488 Copyright (C) 2002 Free Software Foundation, Inc.
 489 .
 490 .P
 491 This document is distributed under the terms of the FDL (GNU Free
 492 Documentation License) version 1.1 or later.
 493 .
 494 You should have received a copy of the FDL on your system, it is also
 495 available on-line at the
 496 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
 497 .
 498 .P
 499 This document is part of
 500 .IR groff ,
 501 the GNU roff distribution.
 502 .
 503 It was written by
 504 .MTO bwarken@mayn.de "Bernd Warken".
 505 .
 506 .
 507 .\" --------------------------------------------------------------------
 508 .SH "SEE ALSO"
 509 .\" --------------------------------------------------------------------
 510 .
 511 .TP
 512 .BR groff (@MAN1EXT@)
 513 An overview of the groff system.
 514 .
 515 .
 516 .TP
 517 .BR troff (@MAN1EXT@)
 518 For details on option
 519 .BR -m .
 520 .
 521 .
 522 .TP
 523 .BR groffer (@MAN1EXT@)
 524 A viewer program for all kinds of roff documents.
 525 .
 526 .
 527 .TP
 528 .BR groff_tmac (@MAN5EXT@)
 529 A general description of groff macro packages.
 530 .
 531 .
 532 .TP
 533 .BR groff (@MAN7EXT@)
 534 A short reference for the groff formatting language.
 535 .
 536 .
 537 .P
 538 A complete reference for all parts of the groff system is found in the
 539 groff
 540 .BR info (1)
 541 file.
 542 .
 543 .
 544 .\" Local Variables:
 545 .\" mode: nroff
 546 .\" End: