groff_trace.man revision 104862
1104862Sru. 2104862Sru.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 3104862Sru.SH NAME 4104862Srugroff_trace \- groff macro package trace.tmac 5104862Sru.SH SYNOPSIS 6104862Sru.\" The .SH was moved to this place to make `apropos' happy. 7104862Sru. 8104862Sru. 9104862Sru.\" -------------------------------------------------------------------- 10104862Sru.\" Legalize 11104862Sru.\" -------------------------------------------------------------------- 12104862Sru. 13104862Sru.ig 14104862Srugroff_trace.7 15104862Sru 16104862SruFile position: <groff-source>/tmac/groff_trace.man 17104862Sru 18104862SruLast update: 14 July 2002 19104862Sru 20104862SruThis file is part of groff, the GNU roff type-setting system. 21104862Sru 22104862SruCopyright (C) 2002 Free Software Foundation, Inc. 23104862Sruwritten by Bernd Warken <bwarken@mayn.de> 24104862Sru 25104862SruPermission is granted to copy, distribute and/or modify this document 26104862Sruunder the terms of the GNU Free Documentation License, Version 1.1 or 27104862Sruany later version published by the Free Software Foundation; with the 28104862SruInvariant Sections being this .ig-section and AUTHOR, with no 29104862SruFront-Cover Texts, and with no Back-Cover Texts. 30104862Sru 31104862SruA copy of the Free Documentation License is included as a file called 32104862SruFDL in the main directory of the groff source package. 33104862Sru.. 34104862Sru. 35104862Sru.\" -------------------------------------------------------------------- 36104862Sru.\" Setup 37104862Sru.\" -------------------------------------------------------------------- 38104862Sru. 39104862Sru.mso www.tmac 40104862Sru. 41104862Sru.if n \{\ 42104862Sru. mso tty-char.tmac 43104862Sru. ftr CR R 44104862Sru. ftr CI I 45104862Sru. ftr CB B 46104862Sru.\} 47104862Sru. 48104862Sru.ds Ellipsis .\|.\|.\&\" 49104862Sru. 50104862Sru.\" Global static variables for inter-macro communication 51104862Sru.rr @+Example_font 52104862Sru. 53104862Sru.\" -------------------------------------------------------------------- 54104862Sru.\" setup for the macro definitions below 55104862Sru.\" 56104862Sru.\" naming: namespace:category_macro.variable_name (experimental) 57104862Sru. 58104862Sru.\" -------------------------------------------------------------------- 59104862Sru.\" configuration of prompt for `.Shell_cmd'* macros 60104862Sru.ds trace:Shell_cmd.prompt_text sh#\" prompt for shell commands 61104862Sru.ds trace:Shell_cmd+.prompt_text >\" prompt on continuation lines 62104862Sru.ds trace:Shell_cmd_base.prompt_font I\" font for prompts 63104862Sru. 64104862Sru.\" automatically determine setup from the configuration above 65104862Sru.als @f trace:Shell_cmd_base.prompt_font\" 66104862Sru.als @t trace:Shell_cmd.prompt_text\" 67104862Sru.als @t+ trace:Shell_cmd+.prompt_text\" 68104862Sru.ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed 69104862Sru.ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed 70104862Sru.nr @w \w'\*[trace:Shell_cmd.prompt]'\" 71104862Sru.nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\" 72104862Sru.ft \*[@f] 73104862Sru.\" Full prompt width is maximum of texts plus 1m 74104862Sru.nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed 75104862Sru.ft 76104862Sru.rm @f 77104862Sru.rm @f+ 78104862Sru.rm @t 79104862Sru.rm @t+ 80104862Sru.rr @w 81104862Sru.rr @w+ 82104862Sru. 83104862Sru.\"-------------------------------------------------------------------- 84104862Sru.\" Ignore all arguments like a comment, even after a .eo call. 85104862Sru.de c 86104862Sru.. 87104862Sru.c -------------------------------------------------------------------- 88104862Sru.de BIR 89104862Sru. ie (\\n[.$] < 3) \ 90104862Sru. BI \\$@ 91104862Sru. el \{\ 92104862Sru. ds @tmp@ \fB\\$1\f[]\fI\\$2\f[] 93104862Sru. shift 2 94104862Sru. Text \\*[@tmp@]\fR\\$*\f[] 95104862Sru. rm @tmp@ 96104862Sru. \} 97104862Sru.. 98104862Sru.c -------------------------------------------------------------------- 99104862Sru.c .Env_var (<env_var_name> [<punct>]) 100104862Sru.c 101104862Sru.c Display an environment variable, with optional punctuation. 102104862Sru.c 103104862Sru.de Env_var 104104862Sru. nh 105104862Sru. SM 106104862Sru. Text \f[CB]\\$1\f[]\\$2 107104862Sru. hy 108104862Sru.. 109104862Sru.c -------------------------------------------------------------------- 110104862Sru.c .Error (<text>...) 111104862Sru.c 112104862Sru.c Print error message to terminal and abort. 113104862Sru.c 114104862Sru.de Error 115104862Sru. tm \\$* 116104862Sru. ab 117104862Sru.. 118104862Sru.c -------------------------------------------------------------------- 119104862Sru.de Example 120104862Sru. if r@+Example_font \ 121104862Sru. Error previous .Example was not terminated by a ./Example 122104862Sru. nr @+Example_font \\n[.f] 123104862Sru. nh 124104862Sru. nf 125104862Sru.c RS \\n[trace:Shell_cmd_base.prompt_width]u 126104862Sru. ft CR 127104862Sru.. 128104862Sru.c -------------------------------------------------------------------- 129104862Sru.de /Example 130104862Sru. if !r@+Example_font \ 131104862Sru. Error no previous call to .Example 132104862Sru. ft \\n[@+Example_font] 133104862Sru.c RE 134104862Sru. fi 135104862Sru. hy 136104862Sru. rr @+Example_font 137104862Sru.. 138104862Sru.c -------------------------------------------------------------------- 139104862Sru.de Macdef 140104862Sru. if (\\n[.$] <= 0) \ 141104862Sru. Error \\$0 needs at least one argument. 142104862Sru. ds @s .\f[B]\\$1\f[]\" 143104862Sru. shift 144104862Sru. if (\\n[.$] > 0) \ 145104862Sru. as @s \~\f[I]\\$*\f[]\" 146104862Sru. IP \\*[@s] 147104862Sru. rm @s 148104862Sru.. 149104862Sru.c -------------------------------------------------------------------- 150104862Sru.de Macdef+ 151104862Sru. br 152104862Sru. ns 153104862Sru. Macdef \\$@ 154104862Sru.. 155104862Sru.c -------------------------------------------------------------------- 156104862Sru.c .Shell_cmd (<CR> [<CI>] ...) 157104862Sru.c 158104862Sru.c A shell command line; display args alternating in fonts CR and CI. 159104862Sru.c 160104862Sru.c Examples: 161104862Sru.c .Shell_cmd "groffer --dpi 100 file" 162104862Sru.c result: `sh# groffer --dpi 100 file' 163104862Sru.c with 'sh#' in font I, the rest in CR 164104862Sru.c 165104862Sru.c .Shell_cmd groffer\~--dpi\~100\~file 166104862Sru.c result: the same as above 167104862Sru.c 168104862Sru.c .Shell_cmd "groffer --dpi=" value " file" 169104862Sru.c result: sh# groffer --dpi=value file 170104862Sru.c with `groffer --dpi=' and `file' in CR; `value' in CI 171104862Sru.c 172104862Sru.c .Shell_cmd groffer\~--dpi= value \~file 173104862Sru.c result: the same as the previous example 174104862Sru.c 175104862Sru.de Shell_cmd 176104862Sru. trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@ 177104862Sru.. 178104862Sru.c -------------------------------------------------------------------- 179104862Sru.c .Shell_cmd+ (<CR> [<CI>] ...) 180104862Sru.c 181104862Sru.c A continuation line for .Shell_cmd. 182104862Sru.c 183104862Sru.de Shell_cmd+ 184104862Sru. trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@ 185104862Sru.. 186104862Sru.c -------------------------------------------------------------------- 187104862Sru.c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...]) 188104862Sru.c 189104862Sru.c A shell command line; display args alternating in fonts CR and CI. 190104862Sru.c Internal, do not use directly. 191104862Sru.c 192104862Sru.c Globals: read-only register @.Shell_cmd_width 193104862Sru.c 194104862Sru.de trace:Shell_cmd_base 195104862Sru. if (\\n[.$] <= 0) \ 196104862Sru. return 197104862Sru. nr @+font \\n[.f]\" 198104862Sru. ds @prompt \\$1\" 199104862Sru. ft CR 200104862Sru. c gap between prompt and command 201104862Sru. nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" 202104862Sru. ds @res \\*[@prompt]\h'\\n[@+gap]u'\" 203104862Sru. shift 204104862Sru. ds @cf CR\" 205104862Sru. while (\\n[.$] > 0) \{\ 206104862Sru. as @res \\f[\\*[@cf]]\\$1\" 207104862Sru. shift 208104862Sru. ie '\\*[@cf]'CR' \ 209104862Sru. ds @cf I\" 210104862Sru. el \ 211104862Sru. ds @cf CR\" 212104862Sru. \} 213104862Sru. br 214104862Sru. ad l 215104862Sru. nh 216104862Sru. nf 217104862Sru. Text \\*[@res]\" 218104862Sru. fi 219104862Sru. hy 220104862Sru. ad 221104862Sru. br 222104862Sru. ft \\n[@+font] 223104862Sru. rr @+font 224104862Sru. rr @+gap 225104862Sru. rm @cf 226104862Sru. rm @res 227104862Sru.. 228104862Sru.c -------------------------------------------------------------------- 229104862Sru.c .Text (<text>...) 230104862Sru.c 231104862Sru.c Treat the arguments as text, no matter how they look. 232104862Sru.c 233104862Sru.de Text 234104862Sru. if (\\n[.$] == 0) \ 235104862Sru. return 236104862Sru. nop \)\\$*\) 237104862Sru.. 238104862Sru.c -------------------------------------------------------------------- 239104862Sru.c .Topic ([<indent>]) 240104862Sru.c 241104862Sru.c A bulleted paragraph. 242104862Sru.c 243104862Sru.de Topic 244104862Sru. ie (\\n[.$] = 0) \ 245104862Sru. .ds @indent 2m\" 246104862Sru. el \ 247104862Sru. .ds @indent \\$1\" 248104862Sru. TP \\*[@indent] 249104862Sru. Text \[bu] 250104862Sru. rm @indent 251104862Sru.. 252104862Sru.c -------------------------------------------------------------------- 253104862Sru.c .TP+ () 254104862Sru.c 255104862Sru.c Continuation line for .TP header. 256104862Sru.c 257104862Sru.de TP+ 258104862Sru. br 259104862Sru. ns 260104862Sru. TP \\$1 261104862Sru.. 262104862Sru.c -------------------------------------------------------------------- 263104862Sru.de 'char 264104862Sru. ds @tmp@ `\f(CR\\$1\f[]' 265104862Sru. shift 266104862Sru. Text \\*[@tmp@]\\$* 267104862Sru. rm @tmp@ 268104862Sru.. 269104862Sru.c -------------------------------------------------------------------- 270104862Sru.de option 271104862Sru. ds @tmp@ \f(CB\\$1\f[] 272104862Sru. shift 1 273104862Sru. Text \\*[@tmp@]\\$* 274104862Sru. rm @tmp@ 275104862Sru.. 276104862Sru.c -------------------------------------------------------------------- 277104862Sru.de argument 278104862Sru. ds @tmp@ \f(CI\\$1\f[] 279104862Sru. shift 1 280104862Sru. Text \\*[@tmp@]\\$* 281104862Sru. rm @tmp@ 282104862Sru.. 283104862Sru.c -------------------------------------------------------------------- 284104862Sru.de request 285104862Sru. ds @tmp@ \f(CB\\$1\f[] 286104862Sru. shift 1 287104862Sru. Text .\\*[@tmp@]\\$* 288104862Sru. rm @tmp@ 289104862Sru.. 290104862Sru.c -------------------------------------------------------------------- 291104862Sru.de escape 292104862Sru. ds @tmp@ \f[CB]\\$1\f[] 293104862Sru. shift 1 294104862Sru. Text \[rs]\\*[@tmp@]\\$* 295104862Sru. rm @tmp@ 296104862Sru.. 297104862Sru. 298104862Sru. 299104862Sru.\" -------------------------------------------------------------------- 300104862Sru.\" SH SYNOPSIS 301104862Sru.\" -------------------------------------------------------------------- 302104862Sru. 303104862Sru.B groff -m trace 304104862Sru.RI [ options\*[Ellipsis] ] 305104862Sru.RI [ files\*[Ellipsis] ] 306104862Sru. 307104862Sru. 308104862Sru.P 309104862SruElements in brackets denote optional arguments, and the ellipsis means 310104862Sruthat there can be any number of arguments of this kind. 311104862Sru. 312104862Sru. 313104862Sru.\" -------------------------------------------------------------------- 314104862Sru.SH DESCRIPTION 315104862Sru.\" -------------------------------------------------------------------- 316104862Sru. 317104862SruThe 318104862Sru.I trace 319104862Srumacro package of 320104862Sru.BR groff (@MAN1EXT@) 321104862Srucan be a valuable tool for debugging documents written in the roff 322104862Sruformatting language. 323104862Sru. 324104862SruA call stack trace is protocolled on standard error, that means, a 325104862Srudiagnostic message is emitted on entering and exiting of a macro call. 326104862Sru. 327104862SruThis greatly eases to track down an error in some macro. 328104862Sru. 329104862Sru. 330104862Sru.P 331104862SruThis tracing process is activated by specifying the groff or troff 332104862Srucommand line option 333104862Sru.BR "-m\~trace" . 334104862SruThis works also with the 335104862Sru.BR groffer (@MAN1EXT@) 336104862Sruviewer program. 337104862Sru. 338104862SruA finer control can be obtained by including the macro file within the 339104862Srudocument by the groff macro call 340104862Sru.BR ".mso\~trace.tmac" . 341104862SruOnly macros that are defined after this line are traced. 342104862Sru. 343104862Sru. 344104862Sru.P 345104862SruIf some other macro package should be traced as well it must be specified 346104862Sruafter 347104862Sru.BR "-m\~trace" 348104862Sruon the command line. 349104862Sru. 350104862Sru. 351104862Sru.P 352104862SruThe macro file 353104862Sru.B trace.tmac 354104862Sruis unusual because it does not contain any macros to be called by a 355104862Sruuser. 356104862Sru. 357104862SruInstead, the existing macro definition and appending facilities are 358104862Srumodified such that they display diagnostic messages. 359104862Sru. 360104862Sru. 361104862Sru.\" -------------------------------------------------------------------- 362104862Sru.SH EXAMPLES 363104862Sru.\" -------------------------------------------------------------------- 364104862Sru. 365104862Sru.P 366104862SruIn the following examples, a roff fragment is fed into groff via 367104862Srustandard input. 368104862Sru. 369104862SruAs we are only interested in the diagnostic messages (standard error) 370104862Sruon the terminal, the normal formatted output (standard output) is 371104862Sruredirected into the nirvana device 372104862Sru.IR /dev/null . 373104862SruThe resulting diagnostic messages are displayed directly below the 374104862Srucorresponding example. 375104862Sru. 376104862Sru. 377104862Sru.\" -------------------------------------------------------------------- 378104862Sru.SS "Command line option" 379104862Sru. 380104862Sru.P 381104862Sru.Shell_cmd "echo '." 382104862Sru.Shell_cmd+ ".de test_macro" 383104862Sru.Shell_cmd+ ".." 384104862Sru.Shell_cmd+ ".test_macro" 385104862Sru.Shell_cmd+ ".test_macro some dummy arguments" 386104862Sru.Shell_cmd+ "' | groff -m trace >/dev/null" 387104862Sru.P 388104862Sru.Example 389104862Sru*** de trace enter: test_macro 390104862Sru*** trace exit: test_macro 391104862Sru*** de trace enter: test_macro "some" "dummy" "arguments" 392104862Sru*** trace exit: test_macro "some" "dummy" "arguments" 393104862Sru./Example 394104862Sru. 395104862Sru.P 396104862SruThe entry and the exit of each macro call is displayed on the terminal 397104862Sru(standard output) \[em] together with the arguments (if any). 398104862Sru. 399104862Sru. 400104862Sru.\" -------------------------------------------------------------------- 401104862Sru.SS "Nested macro calls" 402104862Sru. 403104862Sru.P 404104862Sru.Shell_cmd "echo '." 405104862Sru.Shell_cmd+ ".de child" 406104862Sru.Shell_cmd+ ".." 407104862Sru.Shell_cmd+ ".de parent" 408104862Sru.Shell_cmd+ ".child" 409104862Sru.Shell_cmd+ ".." 410104862Sru.Shell_cmd+ ".parent" 411104862Sru.Shell_cmd+ "' | groff -m trace >/dev/null" 412104862Sru.P 413104862Sru.Example 414104862Sru*** de trace enter: parent 415104862Sru*** de trace enter: child 416104862Sru*** trace exit: child 417104862Sru*** trace exit: parent 418104862Sru./Example 419104862Sru. 420104862Sru.P 421104862SruThis shows that macro calls can be nested. 422104862Sru. 423104862SruThis powerful feature can help to tack down quite complex call stacks. 424104862Sru. 425104862Sru. 426104862Sru.\" -------------------------------------------------------------------- 427104862Sru.SS "Activating with .mso" 428104862Sru. 429104862Sru.Shell_cmd "echo '." 430104862Sru.Shell_cmd+ ".de before" 431104862Sru.Shell_cmd+ .. 432104862Sru.Shell_cmd+ ".mso trace.tmac" 433104862Sru.Shell_cmd+ ".de after" 434104862Sru.Shell_cmd+ .. 435104862Sru.Shell_cmd+ .before 436104862Sru.Shell_cmd+ .after 437104862Sru.Shell_cmd+ .before 438104862Sru.Shell_cmd+ "' | groff >/dev/null" 439104862Sru.P 440104862Sru.Example 441104862Sru*** de trace enter: after 442104862Sru*** trace exit: after 443104862Sru./Example 444104862Sru. 445104862Sru.P 446104862SruHere, the tracing is activated within the document, not by a command 447104862Sruline option. 448104862Sru. 449104862SruAs tracing was not active when macro 450104862Sru.I before 451104862Sruwas defined, no call of this macro is protocolled; on the other hand, 452104862Sruthe macro 453104862Sru.I after 454104862Sruis fully protocolled. 455104862Sru. 456104862Sru. 457104862Sru.\" -------------------------------------------------------------------- 458104862Sru.SH FILES 459104862Sru.\" -------------------------------------------------------------------- 460104862Sru. 461104862SruThe 462104862Sru.I trace 463104862Srumacros are kept in the file 464104862Sru.B trace.tmac 465104862Srulocated in the 466104862Sru.IR "tmac directory" ; 467104862Srusee 468104862Sru.BR groff_tmac (@MAN5EXT@) 469104862Srufor details. 470104862Sru. 471104862Sru. 472104862Sru.\" -------------------------------------------------------------------- 473104862Sru.SH ENVIRONMENT 474104862Sru.\" -------------------------------------------------------------------- 475104862Sru. 476104862Sru.TP 477104862Sru.Env_var $GROFF_TMAC_PATH 478104862SruA colon-separated list of additional tmac directories in which to 479104862Srusearch for macro files; see 480104862Sru.BR groff_tmac (@MAN5EXT@) 481104862Srufor details. 482104862Sru. 483104862Sru. 484104862Sru.\" -------------------------------------------------------------------- 485104862Sru.SH AUTHOR 486104862Sru.\" -------------------------------------------------------------------- 487104862Sru. 488104862SruCopyright (C) 2002 Free Software Foundation, Inc. 489104862Sru. 490104862Sru.P 491104862SruThis document is distributed under the terms of the FDL (GNU Free 492104862SruDocumentation License) version 1.1 or later. 493104862Sru. 494104862SruYou should have received a copy of the FDL on your system, it is also 495104862Sruavailable on-line at the 496104862Sru.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 497104862Sru. 498104862Sru.P 499104862SruThis document is part of 500104862Sru.IR groff , 501104862Sruthe GNU roff distribution. 502104862Sru. 503104862SruIt was written by 504104862Sru.MTO bwarken@mayn.de "Bernd Warken". 505104862Sru. 506104862Sru. 507104862Sru.\" -------------------------------------------------------------------- 508104862Sru.SH "SEE ALSO" 509104862Sru.\" -------------------------------------------------------------------- 510104862Sru. 511104862Sru.TP 512104862Sru.BR groff (@MAN1EXT@) 513104862SruAn overview of the groff system. 514104862Sru. 515104862Sru. 516104862Sru.TP 517104862Sru.BR troff (@MAN1EXT@) 518104862SruFor details on option 519104862Sru.BR -m . 520104862Sru. 521104862Sru. 522104862Sru.TP 523104862Sru.BR groffer (@MAN1EXT@) 524104862SruA viewer program for all kinds of roff documents. 525104862Sru. 526104862Sru. 527104862Sru.TP 528104862Sru.BR groff_tmac (@MAN5EXT@) 529104862SruA general description of groff macro packages. 530104862Sru. 531104862Sru. 532104862Sru.TP 533104862Sru.BR groff (@MAN7EXT@) 534104862SruA short reference for the groff formatting language. 535104862Sru. 536104862Sru. 537104862Sru.P 538104862SruA complete reference for all parts of the groff system is found in the 539104862Srugroff 540104862Sru.BR info (1) 541104862Srufile. 542104862Sru. 543104862Sru. 544104862Sru.\" Local Variables: 545104862Sru.\" mode: nroff 546104862Sru.\" End: 547