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