groff_trace.man revision 256281
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.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 312Elements in brackets denote optional arguments, and the ellipsis means 313that there can be any number of arguments of this kind. 314. 315. 316.\" -------------------------------------------------------------------- 317.SH DESCRIPTION 318.\" -------------------------------------------------------------------- 319. 320The 321.I trace 322macro package of 323.BR groff (@MAN1EXT@) 324can be a valuable tool for debugging documents written in the roff 325formatting language. 326. 327A call stack trace is protocolled on standard error, that means, a 328diagnostic message is emitted on entering and exiting of a macro call. 329. 330This greatly eases to track down an error in some macro. 331. 332. 333.P 334This tracing process is activated by specifying the groff or troff 335command line option 336.BR "-m\~trace" . 337This works also with the 338.BR groffer (@MAN1EXT@) 339viewer program. 340. 341A finer control can be obtained by including the macro file within the 342document by the groff macro call 343.BR ".mso\~trace.tmac" . 344Only macros that are defined after this line are traced. 345. 346. 347.P 348If some other macro package should be traced as well it must be specified 349after 350.BR "-m\~trace" 351on the command line. 352. 353. 354.P 355The macro file 356.B trace.tmac 357is unusual because it does not contain any macros to be called by a 358user. 359. 360Instead, the existing macro definition and appending facilities are 361modified such that they display diagnostic messages. 362. 363. 364.\" -------------------------------------------------------------------- 365.SH EXAMPLES 366.\" -------------------------------------------------------------------- 367. 368.P 369In the following examples, a roff fragment is fed into groff via 370standard input. 371. 372As we are only interested in the diagnostic messages (standard error) 373on the terminal, the normal formatted output (standard output) is 374redirected into the nirvana device 375.IR /dev/null . 376The resulting diagnostic messages are displayed directly below the 377corresponding 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 399The 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 424This shows that macro calls can be nested. 425. 426This 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 449Here, the tracing is activated within the document, not by a command 450line option. 451. 452As tracing was not active when macro 453.I before 454was defined, no call of this macro is protocolled; on the other hand, 455the macro 456.I after 457is fully protocolled. 458. 459. 460.\" -------------------------------------------------------------------- 461.SH FILES 462.\" -------------------------------------------------------------------- 463. 464The 465.I trace 466macros are kept in the file 467.B trace.tmac 468located in the 469.IR "tmac directory" ; 470see 471.BR groff_tmac (@MAN5EXT@) 472for details. 473. 474. 475.\" -------------------------------------------------------------------- 476.SH ENVIRONMENT 477.\" -------------------------------------------------------------------- 478. 479.TP 480.Env_var $GROFF_TMAC_PATH 481A colon-separated list of additional tmac directories in which to 482search for macro files; see 483.BR groff_tmac (@MAN5EXT@) 484for details. 485. 486. 487.\" -------------------------------------------------------------------- 488.SH AUTHOR 489.\" -------------------------------------------------------------------- 490. 491Copyright (C) 2002 Free Software Foundation, Inc. 492. 493.P 494This document is distributed under the terms of the FDL (GNU Free 495Documentation License) version 1.1 or later. 496. 497You should have received a copy of the FDL on your system, it is also 498available on-line at the 499.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 500. 501.P 502This document is part of 503.IR groff , 504the GNU roff distribution. 505. 506It 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@) 516An overview of the groff system. 517. 518. 519.TP 520.BR troff (@MAN1EXT@) 521For details on option 522.BR -m . 523. 524. 525.TP 526.BR groffer (@MAN1EXT@) 527A viewer program for all kinds of roff documents. 528. 529. 530.TP 531.BR groff_tmac (@MAN5EXT@) 532A general description of groff macro packages. 533. 534. 535.TP 536.BR groff (@MAN7EXT@) 537A short reference for the groff formatting language. 538. 539. 540.P 541A complete reference for all parts of the groff system is found in the 542groff 543.BR info (1) 544file. 545. 546.cp \n[groff_trace_C] 547. 548.\" Local Variables: 549.\" mode: nroff 550.\" End: 551