groff_trace.man revision 104862
161981Sbrian. 261981Sbrian.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 361981Sbrian.SH NAME 461981Sbriangroff_trace \- groff macro package trace.tmac 561981Sbrian.SH SYNOPSIS 661981Sbrian.\" The .SH was moved to this place to make `apropos' happy. 761981Sbrian. 861981Sbrian. 961981Sbrian.\" -------------------------------------------------------------------- 1061981Sbrian.\" Legalize 1161981Sbrian.\" -------------------------------------------------------------------- 1261981Sbrian. 1361981Sbrian.ig 1461981Sbriangroff_trace.7 1561981Sbrian 1661981SbrianFile position: <groff-source>/tmac/groff_trace.man 1761981Sbrian 1861981SbrianLast update: 14 July 2002 1961981Sbrian 2061981SbrianThis file is part of groff, the GNU roff type-setting system. 2161981Sbrian 2261981SbrianCopyright (C) 2002 Free Software Foundation, Inc. 2361981Sbrianwritten by Bernd Warken <bwarken@mayn.de> 2461981Sbrian 2565843SbrianPermission is granted to copy, distribute and/or modify this document 2665843Sbrianunder the terms of the GNU Free Documentation License, Version 1.1 or 2765843Sbrianany later version published by the Free Software Foundation; with the 2865843SbrianInvariant Sections being this .ig-section and AUTHOR, with no 2965843SbrianFront-Cover Texts, and with no Back-Cover Texts. 3065843Sbrian 3165843SbrianA copy of the Free Documentation License is included as a file called 3265843SbrianFDL in the main directory of the groff source package. 3365843Sbrian.. 3465843Sbrian. 3561981Sbrian.\" -------------------------------------------------------------------- 3661981Sbrian.\" Setup 3761981Sbrian.\" -------------------------------------------------------------------- 3861981Sbrian. 3961981Sbrian.mso www.tmac 4061981Sbrian. 4161981Sbrian.if n \{\ 4261981Sbrian. mso tty-char.tmac 4361981Sbrian. ftr CR R 4461981Sbrian. ftr CI I 4561981Sbrian. ftr CB B 4661981Sbrian.\} 4761981Sbrian. 4861981Sbrian.ds Ellipsis .\|.\|.\&\" 4961981Sbrian. 5061981Sbrian.\" Global static variables for inter-macro communication 5161981Sbrian.rr @+Example_font 5261981Sbrian. 5361981Sbrian.\" -------------------------------------------------------------------- 5461981Sbrian.\" setup for the macro definitions below 5561981Sbrian.\" 5661981Sbrian.\" naming: namespace:category_macro.variable_name (experimental) 5761981Sbrian. 5861981Sbrian.\" -------------------------------------------------------------------- 5961981Sbrian.\" configuration of prompt for `.Shell_cmd'* macros 6061981Sbrian.ds trace:Shell_cmd.prompt_text sh#\" prompt for shell commands 6161981Sbrian.ds trace:Shell_cmd+.prompt_text >\" prompt on continuation lines 6261981Sbrian.ds trace:Shell_cmd_base.prompt_font I\" font for prompts 63108959Swollman. 64108959Swollman.\" automatically determine setup from the configuration above 6561981Sbrian.als @f trace:Shell_cmd_base.prompt_font\" 6661981Sbrian.als @t trace:Shell_cmd.prompt_text\" 6761981Sbrian.als @t+ trace:Shell_cmd+.prompt_text\" 6861981Sbrian.ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed 6961981Sbrian.ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed 7061981Sbrian.nr @w \w'\*[trace:Shell_cmd.prompt]'\" 7161981Sbrian.nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\" 7261981Sbrian.ft \*[@f] 7361981Sbrian.\" Full prompt width is maximum of texts plus 1m 7461981Sbrian.nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed 7561981Sbrian.ft 7661981Sbrian.rm @f 7762054Sbrian.rm @f+ 7877496Sbrian.rm @t 7977492Sbrian.rm @t+ 8061981Sbrian.rr @w 8161981Sbrian.rr @w+ 8261981Sbrian. 8361981Sbrian.\"-------------------------------------------------------------------- 8461981Sbrian.\" Ignore all arguments like a comment, even after a .eo call. 8561981Sbrian.de c 8662644Ssheldonh.. 8761981Sbrian.c -------------------------------------------------------------------- 88121620Sjesper.de BIR 89123498Sjesper. ie (\\n[.$] < 3) \ 90121620Sjesper. BI \\$@ 9161981Sbrian. el \{\ 9261981Sbrian. ds @tmp@ \fB\\$1\f[]\fI\\$2\f[] 9361981Sbrian. shift 2 9461981Sbrian. Text \\*[@tmp@]\fR\\$*\f[] 9561981Sbrian. rm @tmp@ 9661981Sbrian. \} 9761981Sbrian.. 9861981Sbrian.c -------------------------------------------------------------------- 9961981Sbrian.c .Env_var (<env_var_name> [<punct>]) 10061981Sbrian.c 10194342Sgshapiro.c Display an environment variable, with optional punctuation. 10261981Sbrian.c 10361981Sbrian.de Env_var 10461981Sbrian. nh 10587514Scjc. SM 10661981Sbrian. Text \f[CB]\\$1\f[]\\$2 10761981Sbrian. hy 10861981Sbrian.. 10962274Sbrian.c -------------------------------------------------------------------- 11061981Sbrian.c .Error (<text>...) 11175809Sdirk.c 11275809Sdirk.c Print error message to terminal and abort. 11375809Sdirk.c 11475809Sdirk.de Error 11572677Speter. tm \\$* 11672677Speter. ab 11794342Sgshapiro.. 11872677Speter.c -------------------------------------------------------------------- 11961981Sbrian.de Example 12061981Sbrian. if r@+Example_font \ 12161981Sbrian. Error previous .Example was not terminated by a ./Example 12261981Sbrian. nr @+Example_font \\n[.f] 12387514Scjc. nh 12487514Scjc. nf 125101607Sfanf.c RS \\n[trace:Shell_cmd_base.prompt_width]u 12687514Scjc. ft CR 12787514Scjc.. 12887514Scjc.c -------------------------------------------------------------------- 12987514Scjc.de /Example 13087514Scjc. if !r@+Example_font \ 131135591Sjkoshy. Error no previous call to .Example 13287514Scjc. ft \\n[@+Example_font] 13387514Scjc.c RE 13487514Scjc. fi 13587514Scjc. hy 13687514Scjc. rr @+Example_font 13787514Scjc.. 13887514Scjc.c -------------------------------------------------------------------- 13987514Scjc.de Macdef 14087514Scjc. if (\\n[.$] <= 0) \ 14187514Scjc. Error \\$0 needs at least one argument. 14287514Scjc. ds @s .\f[B]\\$1\f[]\" 14387514Scjc. shift 14487514Scjc. if (\\n[.$] > 0) \ 14587514Scjc. as @s \~\f[I]\\$*\f[]\" 14687514Scjc. IP \\*[@s] 14787514Scjc. rm @s 14887514Scjc.. 14987514Scjc.c -------------------------------------------------------------------- 150105937Sthomas.de Macdef+ 151105937Sthomas. br 152105937Sthomas. ns 153138061Smlaier. Macdef \\$@ 154138061Smlaier.. 155138061Smlaier.c -------------------------------------------------------------------- 15687514Scjc.c .Shell_cmd (<CR> [<CI>] ...) 15787514Scjc.c 15887514Scjc.c A shell command line; display args alternating in fonts CR and CI. 15987514Scjc.c 16087514Scjc.c Examples: 16187514Scjc.c .Shell_cmd "groffer --dpi 100 file" 162128473Sdarrenr.c result: `sh# groffer --dpi 100 file' 163128473Sdarrenr.c with 'sh#' in font I, the rest in CR 164128473Sdarrenr.c 16587514Scjc.c .Shell_cmd groffer\~--dpi\~100\~file 16687514Scjc.c result: the same as above 16787514Scjc.c 16887514Scjc.c .Shell_cmd "groffer --dpi=" value " file" 16987514Scjc.c result: sh# groffer --dpi=value file 17087514Scjc.c with `groffer --dpi=' and `file' in CR; `value' in CI 17187514Scjc.c 17287514Scjc.c .Shell_cmd groffer\~--dpi= value \~file 17387514Scjc.c result: the same as the previous example 17487514Scjc.c 17587514Scjc.de Shell_cmd 17687514Scjc. trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@ 17787514Scjc.. 17861981Sbrian.c -------------------------------------------------------------------- 17961981Sbrian.c .Shell_cmd+ (<CR> [<CI>] ...) 18065843Sbrian.c 18165843Sbrian.c A continuation line for .Shell_cmd. 18265843Sbrian.c 18365843Sbrian.de Shell_cmd+ 18465843Sbrian. trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@ 18565843Sbrian.. 18665843Sbrian.c -------------------------------------------------------------------- 18765843Sbrian.c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...]) 18865843Sbrian.c 18965843Sbrian.c A shell command line; display args alternating in fonts CR and CI. 19061981Sbrian.c Internal, do not use directly. 19161981Sbrian.c 19261981Sbrian.c Globals: read-only register @.Shell_cmd_width 19361981Sbrian.c 19461981Sbrian.de trace:Shell_cmd_base 19561981Sbrian. if (\\n[.$] <= 0) \ 19661981Sbrian. return 19761981Sbrian. nr @+font \\n[.f]\" 19861981Sbrian. ds @prompt \\$1\" 19961981Sbrian. ft CR 20061981Sbrian. c gap between prompt and command 20161981Sbrian. nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" 20261981Sbrian. ds @res \\*[@prompt]\h'\\n[@+gap]u'\" 20361981Sbrian. shift 20461981Sbrian. ds @cf CR\" 20561981Sbrian. while (\\n[.$] > 0) \{\ 20661981Sbrian. as @res \\f[\\*[@cf]]\\$1\" 20761981Sbrian. shift 20862206Sbrian. ie '\\*[@cf]'CR' \ 20962155Sbrian. ds @cf I\" 210103948Sbrian. el \ 211129424Sjoe. ds @cf CR\" 21262155Sbrian. \} 21361981Sbrian. br 21461981Sbrian. ad l 21561981Sbrian. nh 21661981Sbrian. nf 21761981Sbrian. Text \\*[@res]\" 21861981Sbrian. fi 21965843Sbrian. hy 22065843Sbrian. ad 22165843Sbrian. br 22265843Sbrian. ft \\n[@+font] 22365843Sbrian. rr @+font 22465843Sbrian. rr @+gap 22565843Sbrian. rm @cf 22665843Sbrian. rm @res 22765843Sbrian.. 22865843Sbrian.c -------------------------------------------------------------------- 22961981Sbrian.c .Text (<text>...) 23061981Sbrian.c 23161981Sbrian.c Treat the arguments as text, no matter how they look. 23261981Sbrian.c 23361981Sbrian.de Text 23461981Sbrian. if (\\n[.$] == 0) \ 23561981Sbrian. return 23661981Sbrian. nop \)\\$*\) 23761981Sbrian.. 23861981Sbrian.c -------------------------------------------------------------------- 23961981Sbrian.c .Topic ([<indent>]) 24061981Sbrian.c 24161981Sbrian.c A bulleted paragraph. 24261981Sbrian.c 24361981Sbrian.de Topic 24461981Sbrian. ie (\\n[.$] = 0) \ 24561981Sbrian. .ds @indent 2m\" 24661981Sbrian. el \ 24761981Sbrian. .ds @indent \\$1\" 24861981Sbrian. TP \\*[@indent] 24961981Sbrian. Text \[bu] 25061981Sbrian. rm @indent 25161981Sbrian.. 25261981Sbrian.c -------------------------------------------------------------------- 25361981Sbrian.c .TP+ () 25461981Sbrian.c 25561981Sbrian.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 309Elements in brackets denote optional arguments, and the ellipsis means 310that there can be any number of arguments of this kind. 311. 312. 313.\" -------------------------------------------------------------------- 314.SH DESCRIPTION 315.\" -------------------------------------------------------------------- 316. 317The 318.I trace 319macro package of 320.BR groff (@MAN1EXT@) 321can be a valuable tool for debugging documents written in the roff 322formatting language. 323. 324A call stack trace is protocolled on standard error, that means, a 325diagnostic message is emitted on entering and exiting of a macro call. 326. 327This greatly eases to track down an error in some macro. 328. 329. 330.P 331This tracing process is activated by specifying the groff or troff 332command line option 333.BR "-m\~trace" . 334This works also with the 335.BR groffer (@MAN1EXT@) 336viewer program. 337. 338A finer control can be obtained by including the macro file within the 339document by the groff macro call 340.BR ".mso\~trace.tmac" . 341Only macros that are defined after this line are traced. 342. 343. 344.P 345If some other macro package should be traced as well it must be specified 346after 347.BR "-m\~trace" 348on the command line. 349. 350. 351.P 352The macro file 353.B trace.tmac 354is unusual because it does not contain any macros to be called by a 355user. 356. 357Instead, the existing macro definition and appending facilities are 358modified such that they display diagnostic messages. 359. 360. 361.\" -------------------------------------------------------------------- 362.SH EXAMPLES 363.\" -------------------------------------------------------------------- 364. 365.P 366In the following examples, a roff fragment is fed into groff via 367standard input. 368. 369As we are only interested in the diagnostic messages (standard error) 370on the terminal, the normal formatted output (standard output) is 371redirected into the nirvana device 372.IR /dev/null . 373The resulting diagnostic messages are displayed directly below the 374corresponding 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 396The 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 421This shows that macro calls can be nested. 422. 423This 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 446Here, the tracing is activated within the document, not by a command 447line option. 448. 449As tracing was not active when macro 450.I before 451was defined, no call of this macro is protocolled; on the other hand, 452the macro 453.I after 454is fully protocolled. 455. 456. 457.\" -------------------------------------------------------------------- 458.SH FILES 459.\" -------------------------------------------------------------------- 460. 461The 462.I trace 463macros are kept in the file 464.B trace.tmac 465located in the 466.IR "tmac directory" ; 467see 468.BR groff_tmac (@MAN5EXT@) 469for details. 470. 471. 472.\" -------------------------------------------------------------------- 473.SH ENVIRONMENT 474.\" -------------------------------------------------------------------- 475. 476.TP 477.Env_var $GROFF_TMAC_PATH 478A colon-separated list of additional tmac directories in which to 479search for macro files; see 480.BR groff_tmac (@MAN5EXT@) 481for details. 482. 483. 484.\" -------------------------------------------------------------------- 485.SH AUTHOR 486.\" -------------------------------------------------------------------- 487. 488Copyright (C) 2002 Free Software Foundation, Inc. 489. 490.P 491This document is distributed under the terms of the FDL (GNU Free 492Documentation License) version 1.1 or later. 493. 494You should have received a copy of the FDL on your system, it is also 495available on-line at the 496.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 497. 498.P 499This document is part of 500.IR groff , 501the GNU roff distribution. 502. 503It 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@) 513An overview of the groff system. 514. 515. 516.TP 517.BR troff (@MAN1EXT@) 518For details on option 519.BR -m . 520. 521. 522.TP 523.BR groffer (@MAN1EXT@) 524A viewer program for all kinds of roff documents. 525. 526. 527.TP 528.BR groff_tmac (@MAN5EXT@) 529A general description of groff macro packages. 530. 531. 532.TP 533.BR groff (@MAN7EXT@) 534A short reference for the groff formatting language. 535. 536. 537.P 538A complete reference for all parts of the groff system is found in the 539groff 540.BR info (1) 541file. 542. 543. 544.\" Local Variables: 545.\" mode: nroff 546.\" End: 547