groff_trace.man revision 104862
1. 2.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 3.SH NAME 4groff_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 14groff_trace.7 15 16File position: <groff-source>/tmac/groff_trace.man 17 18Last update: 14 July 2002 19 20This file is part of groff, the GNU roff type-setting system. 21 22Copyright (C) 2002 Free Software Foundation, Inc. 23written by Bernd Warken <bwarken@mayn.de> 24 25Permission is granted to copy, distribute and/or modify this document 26under the terms of the GNU Free Documentation License, Version 1.1 or 27any later version published by the Free Software Foundation; with the 28Invariant Sections being this .ig-section and AUTHOR, with no 29Front-Cover Texts, and with no Back-Cover Texts. 30 31A copy of the Free Documentation License is included as a file called 32FDL 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 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