/contrib/groff/tmac/groff_trace.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 550 lines · 544 code · 6 blank · 0 comment · 0 complexity · 73b8a9d90cb942a9914eaaa0d99002ed MD5 · raw file

  1. .
  2. .TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  3. .SH NAME
  4. groff_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
  14. groff_trace.7
  15. File position: <groff-source>/tmac/groff_trace.man
  16. Last update: 14 July 2002
  17. This file is part of groff, the GNU roff type-setting system.
  18. Copyright (C) 2002 Free Software Foundation, Inc.
  19. written by Bernd Warken <bwarken@mayn.de>
  20. Permission is granted to copy, distribute and/or modify this document
  21. under the terms of the GNU Free Documentation License, Version 1.1 or
  22. any later version published by the Free Software Foundation; with the
  23. Invariant Sections being this .ig-section and AUTHOR, with no
  24. Front-Cover Texts, and with no Back-Cover Texts.
  25. A copy of the Free Documentation License is included as a file called
  26. FDL in the main directory of the groff source package.
  27. ..
  28. .
  29. .\" --------------------------------------------------------------------
  30. .\" Setup
  31. .\" --------------------------------------------------------------------
  32. .
  33. .do nr groff_trace_C \n[.C]
  34. .cp 0
  35. .
  36. .mso www.tmac
  37. .
  38. .if n \{\
  39. . mso tty-char.tmac
  40. . ftr CR R
  41. . ftr CI I
  42. . ftr CB B
  43. .\}
  44. .
  45. .ds Ellipsis .\|.\|.\&\"
  46. .
  47. .\" Global static variables for inter-macro communication
  48. .rr @+Example_font
  49. .
  50. .\" --------------------------------------------------------------------
  51. .\" setup for the macro definitions below
  52. .\"
  53. .\" naming: namespace:category_macro.variable_name (experimental)
  54. .
  55. .\" --------------------------------------------------------------------
  56. .\" configuration of prompt for `.Shell_cmd'* macros
  57. .ds trace:Shell_cmd.prompt_text sh#\" prompt for shell commands
  58. .ds trace:Shell_cmd+.prompt_text >\" prompt on continuation lines
  59. .ds trace:Shell_cmd_base.prompt_font I\" font for prompts
  60. .
  61. .\" automatically determine setup from the configuration above
  62. .als @f trace:Shell_cmd_base.prompt_font\"
  63. .als @t trace:Shell_cmd.prompt_text\"
  64. .als @t+ trace:Shell_cmd+.prompt_text\"
  65. .ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed
  66. .ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed
  67. .nr @w \w'\*[trace:Shell_cmd.prompt]'\"
  68. .nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\"
  69. .ft \*[@f]
  70. .\" Full prompt width is maximum of texts plus 1m
  71. .nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
  72. .ft
  73. .rm @f
  74. .rm @f+
  75. .rm @t
  76. .rm @t+
  77. .rr @w
  78. .rr @w+
  79. .
  80. .\"--------------------------------------------------------------------
  81. .\" Ignore all arguments like a comment, even after a .eo call.
  82. .de c
  83. ..
  84. .c --------------------------------------------------------------------
  85. .de BIR
  86. . ie (\\n[.$] < 3) \
  87. . BI \\$@
  88. . el \{\
  89. . ds @tmp@ \fB\\$1\f[]\fI\\$2\f[]
  90. . shift 2
  91. . Text \\*[@tmp@]\fR\\$*\f[]
  92. . rm @tmp@
  93. . \}
  94. ..
  95. .c --------------------------------------------------------------------
  96. .c .Env_var (<env_var_name> [<punct>])
  97. .c
  98. .c Display an environment variable, with optional punctuation.
  99. .c
  100. .de Env_var
  101. . nh
  102. . SM
  103. . Text \f[CB]\\$1\f[]\\$2
  104. . hy
  105. ..
  106. .c --------------------------------------------------------------------
  107. .c .Error (<text>...)
  108. .c
  109. .c Print error message to terminal and abort.
  110. .c
  111. .de Error
  112. . tm \\$*
  113. . ab
  114. ..
  115. .c --------------------------------------------------------------------
  116. .de Example
  117. . if r@+Example_font \
  118. . Error previous .Example was not terminated by a ./Example
  119. . nr @+Example_font \\n[.f]
  120. . nh
  121. . nf
  122. .c RS \\n[trace:Shell_cmd_base.prompt_width]u
  123. . ft CR
  124. ..
  125. .c --------------------------------------------------------------------
  126. .de /Example
  127. . if !r@+Example_font \
  128. . Error no previous call to .Example
  129. . ft \\n[@+Example_font]
  130. .c RE
  131. . fi
  132. . hy
  133. . rr @+Example_font
  134. ..
  135. .c --------------------------------------------------------------------
  136. .de Macdef
  137. . if (\\n[.$] <= 0) \
  138. . Error \\$0 needs at least one argument.
  139. . ds @s .\f[B]\\$1\f[]\"
  140. . shift
  141. . if (\\n[.$] > 0) \
  142. . as @s \~\f[I]\\$*\f[]\"
  143. . IP \\*[@s]
  144. . rm @s
  145. ..
  146. .c --------------------------------------------------------------------
  147. .de Macdef+
  148. . br
  149. . ns
  150. . Macdef \\$@
  151. ..
  152. .c --------------------------------------------------------------------
  153. .c .Shell_cmd (<CR> [<CI>] ...)
  154. .c
  155. .c A shell command line; display args alternating in fonts CR and CI.
  156. .c
  157. .c Examples:
  158. .c .Shell_cmd "groffer --dpi 100 file"
  159. .c result: `sh# groffer --dpi 100 file'
  160. .c with 'sh#' in font I, the rest in CR
  161. .c
  162. .c .Shell_cmd groffer\~--dpi\~100\~file
  163. .c result: the same as above
  164. .c
  165. .c .Shell_cmd "groffer --dpi=" value " file"
  166. .c result: sh# groffer --dpi=value file
  167. .c with `groffer --dpi=' and `file' in CR; `value' in CI
  168. .c
  169. .c .Shell_cmd groffer\~--dpi= value \~file
  170. .c result: the same as the previous example
  171. .c
  172. .de Shell_cmd
  173. . trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@
  174. ..
  175. .c --------------------------------------------------------------------
  176. .c .Shell_cmd+ (<CR> [<CI>] ...)
  177. .c
  178. .c A continuation line for .Shell_cmd.
  179. .c
  180. .de Shell_cmd+
  181. . trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@
  182. ..
  183. .c --------------------------------------------------------------------
  184. .c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...])
  185. .c
  186. .c A shell command line; display args alternating in fonts CR and CI.
  187. .c Internal, do not use directly.
  188. .c
  189. .c Globals: read-only register @.Shell_cmd_width
  190. .c
  191. .de trace:Shell_cmd_base
  192. . if (\\n[.$] <= 0) \
  193. . return
  194. . nr @+font \\n[.f]\"
  195. . ds @prompt \\$1\"
  196. . ft CR
  197. . c gap between prompt and command
  198. . nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
  199. . ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
  200. . shift
  201. . ds @cf CR\"
  202. . while (\\n[.$] > 0) \{\
  203. . as @res \\f[\\*[@cf]]\\$1\"
  204. . shift
  205. . ie '\\*[@cf]'CR' \
  206. . ds @cf I\"
  207. . el \
  208. . ds @cf CR\"
  209. . \}
  210. . br
  211. . ad l
  212. . nh
  213. . nf
  214. . Text \\*[@res]\"
  215. . fi
  216. . hy
  217. . ad
  218. . br
  219. . ft \\n[@+font]
  220. . rr @+font
  221. . rr @+gap
  222. . rm @cf
  223. . rm @res
  224. ..
  225. .c --------------------------------------------------------------------
  226. .c .Text (<text>...)
  227. .c
  228. .c Treat the arguments as text, no matter how they look.
  229. .c
  230. .de Text
  231. . if (\\n[.$] == 0) \
  232. . return
  233. . nop \)\\$*\)
  234. ..
  235. .c --------------------------------------------------------------------
  236. .c .Topic ([<indent>])
  237. .c
  238. .c A bulleted paragraph.
  239. .c
  240. .de Topic
  241. . ie (\\n[.$] = 0) \
  242. . .ds @indent 2m\"
  243. . el \
  244. . .ds @indent \\$1\"
  245. . TP \\*[@indent]
  246. . Text \[bu]
  247. . rm @indent
  248. ..
  249. .c --------------------------------------------------------------------
  250. .c .TP+ ()
  251. .c
  252. .c Continuation line for .TP header.
  253. .c
  254. .de TP+
  255. . br
  256. . ns
  257. . TP \\$1
  258. ..
  259. .c --------------------------------------------------------------------
  260. .de 'char
  261. . ds @tmp@ `\f(CR\\$1\f[]'
  262. . shift
  263. . Text \\*[@tmp@]\\$*
  264. . rm @tmp@
  265. ..
  266. .c --------------------------------------------------------------------
  267. .de option
  268. . ds @tmp@ \f(CB\\$1\f[]
  269. . shift 1
  270. . Text \\*[@tmp@]\\$*
  271. . rm @tmp@
  272. ..
  273. .c --------------------------------------------------------------------
  274. .de argument
  275. . ds @tmp@ \f(CI\\$1\f[]
  276. . shift 1
  277. . Text \\*[@tmp@]\\$*
  278. . rm @tmp@
  279. ..
  280. .c --------------------------------------------------------------------
  281. .de request
  282. . ds @tmp@ \f(CB\\$1\f[]
  283. . shift 1
  284. . Text .\\*[@tmp@]\\$*
  285. . rm @tmp@
  286. ..
  287. .c --------------------------------------------------------------------
  288. .de escape
  289. . ds @tmp@ \f[CB]\\$1\f[]
  290. . shift 1
  291. . Text \[rs]\\*[@tmp@]\\$*
  292. . rm @tmp@
  293. ..
  294. .
  295. .
  296. .\" --------------------------------------------------------------------
  297. .\" SH SYNOPSIS
  298. .\" --------------------------------------------------------------------
  299. .
  300. .B groff -m trace
  301. .RI [ options\*[Ellipsis] ]
  302. .RI [ files\*[Ellipsis] ]
  303. .
  304. .
  305. .P
  306. Elements in brackets denote optional arguments, and the ellipsis means
  307. that there can be any number of arguments of this kind.
  308. .
  309. .
  310. .\" --------------------------------------------------------------------
  311. .SH DESCRIPTION
  312. .\" --------------------------------------------------------------------
  313. .
  314. The
  315. .I trace
  316. macro package of
  317. .BR groff (@MAN1EXT@)
  318. can be a valuable tool for debugging documents written in the roff
  319. formatting language.
  320. .
  321. A call stack trace is protocolled on standard error, that means, a
  322. diagnostic message is emitted on entering and exiting of a macro call.
  323. .
  324. This greatly eases to track down an error in some macro.
  325. .
  326. .
  327. .P
  328. This tracing process is activated by specifying the groff or troff
  329. command line option
  330. .BR "-m\~trace" .
  331. This works also with the
  332. .BR groffer (@MAN1EXT@)
  333. viewer program.
  334. .
  335. A finer control can be obtained by including the macro file within the
  336. document by the groff macro call
  337. .BR ".mso\~trace.tmac" .
  338. Only macros that are defined after this line are traced.
  339. .
  340. .
  341. .P
  342. If some other macro package should be traced as well it must be specified
  343. after
  344. .BR "-m\~trace"
  345. on the command line.
  346. .
  347. .
  348. .P
  349. The macro file
  350. .B trace.tmac
  351. is unusual because it does not contain any macros to be called by a
  352. user.
  353. .
  354. Instead, the existing macro definition and appending facilities are
  355. modified such that they display diagnostic messages.
  356. .
  357. .
  358. .\" --------------------------------------------------------------------
  359. .SH EXAMPLES
  360. .\" --------------------------------------------------------------------
  361. .
  362. .P
  363. In the following examples, a roff fragment is fed into groff via
  364. standard input.
  365. .
  366. As we are only interested in the diagnostic messages (standard error)
  367. on the terminal, the normal formatted output (standard output) is
  368. redirected into the nirvana device
  369. .IR /dev/null .
  370. The resulting diagnostic messages are displayed directly below the
  371. corresponding example.
  372. .
  373. .
  374. .\" --------------------------------------------------------------------
  375. .SS "Command line option"
  376. .
  377. .P
  378. .Shell_cmd "echo '."
  379. .Shell_cmd+ ".de test_macro"
  380. .Shell_cmd+ ".."
  381. .Shell_cmd+ ".test_macro"
  382. .Shell_cmd+ ".test_macro some dummy arguments"
  383. .Shell_cmd+ "' | groff -m trace >/dev/null"
  384. .P
  385. .Example
  386. *** de trace enter: test_macro
  387. *** trace exit: test_macro
  388. *** de trace enter: test_macro "some" "dummy" "arguments"
  389. *** trace exit: test_macro "some" "dummy" "arguments"
  390. ./Example
  391. .
  392. .P
  393. The entry and the exit of each macro call is displayed on the terminal
  394. (standard output) \[em] together with the arguments (if any).
  395. .
  396. .
  397. .\" --------------------------------------------------------------------
  398. .SS "Nested macro calls"
  399. .
  400. .P
  401. .Shell_cmd "echo '."
  402. .Shell_cmd+ ".de child"
  403. .Shell_cmd+ ".."
  404. .Shell_cmd+ ".de parent"
  405. .Shell_cmd+ ".child"
  406. .Shell_cmd+ ".."
  407. .Shell_cmd+ ".parent"
  408. .Shell_cmd+ "' | groff -m trace >/dev/null"
  409. .P
  410. .Example
  411. *** de trace enter: parent
  412. *** de trace enter: child
  413. *** trace exit: child
  414. *** trace exit: parent
  415. ./Example
  416. .
  417. .P
  418. This shows that macro calls can be nested.
  419. .
  420. This powerful feature can help to tack down quite complex call stacks.
  421. .
  422. .
  423. .\" --------------------------------------------------------------------
  424. .SS "Activating with .mso"
  425. .
  426. .Shell_cmd "echo '."
  427. .Shell_cmd+ ".de before"
  428. .Shell_cmd+ ..
  429. .Shell_cmd+ ".mso trace.tmac"
  430. .Shell_cmd+ ".de after"
  431. .Shell_cmd+ ..
  432. .Shell_cmd+ .before
  433. .Shell_cmd+ .after
  434. .Shell_cmd+ .before
  435. .Shell_cmd+ "' | groff >/dev/null"
  436. .P
  437. .Example
  438. *** de trace enter: after
  439. *** trace exit: after
  440. ./Example
  441. .
  442. .P
  443. Here, the tracing is activated within the document, not by a command
  444. line option.
  445. .
  446. As tracing was not active when macro
  447. .I before
  448. was defined, no call of this macro is protocolled; on the other hand,
  449. the macro
  450. .I after
  451. is fully protocolled.
  452. .
  453. .
  454. .\" --------------------------------------------------------------------
  455. .SH FILES
  456. .\" --------------------------------------------------------------------
  457. .
  458. The
  459. .I trace
  460. macros are kept in the file
  461. .B trace.tmac
  462. located in the
  463. .IR "tmac directory" ;
  464. see
  465. .BR groff_tmac (@MAN5EXT@)
  466. for details.
  467. .
  468. .
  469. .\" --------------------------------------------------------------------
  470. .SH ENVIRONMENT
  471. .\" --------------------------------------------------------------------
  472. .
  473. .TP
  474. .Env_var $GROFF_TMAC_PATH
  475. A colon-separated list of additional tmac directories in which to
  476. search for macro files; see
  477. .BR groff_tmac (@MAN5EXT@)
  478. for details.
  479. .
  480. .
  481. .\" --------------------------------------------------------------------
  482. .SH AUTHOR
  483. .\" --------------------------------------------------------------------
  484. .
  485. Copyright (C) 2002 Free Software Foundation, Inc.
  486. .
  487. .P
  488. This document is distributed under the terms of the FDL (GNU Free
  489. Documentation License) version 1.1 or later.
  490. .
  491. You should have received a copy of the FDL on your system, it is also
  492. available on-line at the
  493. .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
  494. .
  495. .P
  496. This document is part of
  497. .IR groff ,
  498. the GNU roff distribution.
  499. .
  500. It was written by
  501. .MTO bwarken@mayn.de "Bernd Warken".
  502. .
  503. .
  504. .\" --------------------------------------------------------------------
  505. .SH "SEE ALSO"
  506. .\" --------------------------------------------------------------------
  507. .
  508. .TP
  509. .BR groff (@MAN1EXT@)
  510. An overview of the groff system.
  511. .
  512. .
  513. .TP
  514. .BR troff (@MAN1EXT@)
  515. For details on option
  516. .BR -m .
  517. .
  518. .
  519. .TP
  520. .BR groffer (@MAN1EXT@)
  521. A viewer program for all kinds of roff documents.
  522. .
  523. .
  524. .TP
  525. .BR groff_tmac (@MAN5EXT@)
  526. A general description of groff macro packages.
  527. .
  528. .
  529. .TP
  530. .BR groff (@MAN7EXT@)
  531. A short reference for the groff formatting language.
  532. .
  533. .
  534. .P
  535. A complete reference for all parts of the groff system is found in the
  536. groff
  537. .BR info (1)
  538. file.
  539. .
  540. .cp \n[groff_trace_C]
  541. .
  542. .\" Local Variables:
  543. .\" mode: nroff
  544. .\" End: