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