/contrib/groff/tmac/groff_trace.man

  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: