xref: /freebsd-10.3-release/contrib/groff/tmac/groff_trace.man

.
.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
.SH NAME
groff_trace \- groff macro package trace.tmac
.SH SYNOPSIS
.\" The .SH was moved to this place to make `apropos' happy.
.
.
.\" --------------------------------------------------------------------
.\" Legalize
.\" --------------------------------------------------------------------
.
.ig
groff_trace.7

File position: <groff-source>/tmac/groff_trace.man

Last update: 14 July 2002

This file is part of groff, the GNU roff type-setting system.

Copyright (C) 2002 Free Software Foundation, Inc.
written by Bernd Warken <bwarken@mayn.de>

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being this .ig-section and AUTHOR, with no
Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
..
.
.\" --------------------------------------------------------------------
.\" Setup
.\" --------------------------------------------------------------------
.
.mso www.tmac
.
.if n \{\
.  mso tty-char.tmac
.  ftr CR R
.  ftr CI I
.  ftr CB B
.\}
.
.ds Ellipsis .\|.\|.\&\"
.
.\" Global static variables for inter-macro communication
.rr @+Example_font
.
.\" --------------------------------------------------------------------
.\" setup for the macro definitions below
.\"
.\" naming:  namespace:category_macro.variable_name  (experimental)
.
.\" --------------------------------------------------------------------
.\" configuration of prompt for `.Shell_cmd'* macros
.ds trace:Shell_cmd.prompt_text sh#\"    prompt for shell commands
.ds trace:Shell_cmd+.prompt_text >\"     prompt on continuation lines
.ds trace:Shell_cmd_base.prompt_font I\" font for prompts
.
.\" automatically determine setup from the configuration above
.als @f trace:Shell_cmd_base.prompt_font\"
.als @t trace:Shell_cmd.prompt_text\"
.als @t+ trace:Shell_cmd+.prompt_text\"
.ds trace:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\"            needed
.ds trace:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\"          needed
.nr @w \w'\*[trace:Shell_cmd.prompt]'\"
.nr @w+ \w'\*[trace:Shell_cmd+.prompt]'\"
.ft \*[@f]
.\" Full prompt width is maximum of texts plus 1m
.nr trace:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
.ft
.rm @f
.rm @f+
.rm @t
.rm @t+
.rr @w
.rr @w+
.
.\"--------------------------------------------------------------------
.\" Ignore all arguments like a comment, even after a .eo call.
.de c
..
.c --------------------------------------------------------------------
.de BIR
.  ie (\\n[.$] < 3) \
.    BI \\$@
.  el \{\
.    ds @tmp@ \fB\\$1\f[]\fI\\$2\f[]
.    shift 2
.    Text \\*[@tmp@]\fR\\$*\f[]
.    rm @tmp@
.  \}
..
.c --------------------------------------------------------------------
.c .Env_var  (<env_var_name> [<punct>])
.c
.c Display an environment variable, with optional punctuation.
.c
.de Env_var
.  nh
.  SM
.  Text \f[CB]\\$1\f[]\\$2
.  hy
..
.c --------------------------------------------------------------------
.c .Error  (<text>...)
.c
.c Print error message to terminal and abort.
.c
.de Error
.  tm \\$*
.  ab
..
.c --------------------------------------------------------------------
.de Example
.  if r@+Example_font \
.    Error previous .Example was not terminated by a ./Example
.  nr @+Example_font \\n[.f]
.  nh
.  nf
.c  RS \\n[trace:Shell_cmd_base.prompt_width]u
.  ft CR
..
.c --------------------------------------------------------------------
.de /Example
.  if !r@+Example_font \
.    Error no previous call to .Example
.  ft \\n[@+Example_font]
.c  RE
.  fi
.  hy
.  rr @+Example_font
..
.c --------------------------------------------------------------------
.de Macdef
.  if (\\n[.$] <= 0) \
.    Error \\$0 needs at least one argument.
.  ds @s .\f[B]\\$1\f[]\"
.  shift
.  if (\\n[.$] > 0) \
.    as @s \~\f[I]\\$*\f[]\"
.  IP \\*[@s]
.  rm @s
..
.c --------------------------------------------------------------------
.de Macdef+
.  br
.  ns
.  Macdef \\$@
..
.c --------------------------------------------------------------------
.c .Shell_cmd  (<CR> [<CI>] ...)
.c
.c A shell command line; display args alternating in fonts CR and CI.
.c
.c Examples:
.c   .Shell_cmd "groffer --dpi 100 file"
.c     result: `sh#  groffer --dpi 100 file'
.c             with 'sh#' in font I, the rest in CR
.c
.c   .Shell_cmd groffer\~--dpi\~100\~file
.c     result: the same as above
.c
.c   .Shell_cmd "groffer --dpi=" value " file"
.c     result: sh#  groffer --dpi=value file
.c             with `groffer --dpi=' and `file' in CR; `value' in CI
.c
.c   .Shell_cmd groffer\~--dpi= value \~file
.c     result: the same as the previous example
.c
.de Shell_cmd
.  trace:Shell_cmd_base "\*[trace:Shell_cmd.prompt]" \\$@
..
.c --------------------------------------------------------------------
.c .Shell_cmd+  (<CR> [<CI>] ...)
.c
.c A continuation line for .Shell_cmd.
.c
.de Shell_cmd+
.  trace:Shell_cmd_base "\*[trace:Shell_cmd+.prompt]" \\$@
..
.c --------------------------------------------------------------------
.c .Shell_cmd_base  (<prompt> [<CR> [<CI>] ...])
.c
.c A shell command line; display args alternating in fonts CR and CI.
.c Internal, do not use directly.
.c
.c Globals: read-only register @.Shell_cmd_width
.c
.de trace:Shell_cmd_base
.  if (\\n[.$] <= 0) \
.    return
.  nr @+font \\n[.f]\"
.  ds @prompt \\$1\"
.  ft CR
.  c gap between prompt and command
.  nr @+gap \\n[trace:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
.  ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
.  shift
.  ds @cf CR\"
.  while (\\n[.$] > 0) \{\
.    as @res \\f[\\*[@cf]]\\$1\"
.    shift
.    ie '\\*[@cf]'CR' \
.      ds @cf I\"
.    el \
.      ds @cf CR\"
.  \}
.  br
.  ad l
.  nh
.  nf
.  Text \\*[@res]\"
.  fi
.  hy
.  ad
.  br
.  ft \\n[@+font]
.  rr @+font
.  rr @+gap
.  rm @cf
.  rm @res
..
.c --------------------------------------------------------------------
.c .Text  (<text>...)
.c
.c Treat the arguments as text, no matter how they look.
.c
.de Text
.  if (\\n[.$] == 0) \
.    return
.  nop \)\\$*\)
..
.c --------------------------------------------------------------------
.c .Topic  ([<indent>])
.c
.c A bulleted paragraph.
.c
.de Topic
.  ie (\\n[.$] = 0) \
.    .ds @indent 2m\"
.  el \
.    .ds @indent \\$1\"
.  TP \\*[@indent]
.  Text \[bu]
.  rm @indent
..
.c --------------------------------------------------------------------
.c .TP+  ()
.c
.c Continuation line for .TP header.
.c
.de TP+
.  br
.  ns
.  TP \\$1
..
.c --------------------------------------------------------------------
.de 'char
.  ds @tmp@ `\f(CR\\$1\f[]'
.  shift
.  Text \\*[@tmp@]\\$*
.  rm @tmp@
..
.c --------------------------------------------------------------------
.de option
.  ds @tmp@ \f(CB\\$1\f[]
.  shift 1
.  Text \\*[@tmp@]\\$*
.  rm @tmp@
..
.c --------------------------------------------------------------------
.de argument
.  ds @tmp@ \f(CI\\$1\f[]
.  shift 1
.  Text \\*[@tmp@]\\$*
.  rm @tmp@
..
.c --------------------------------------------------------------------
.de request
.  ds @tmp@ \f(CB\\$1\f[]
.  shift 1
.  Text .\\*[@tmp@]\\$*
.  rm @tmp@
..
.c --------------------------------------------------------------------
.de escape
.  ds @tmp@ \f[CB]\\$1\f[]
.  shift 1
.  Text \[rs]\\*[@tmp@]\\$*
.  rm @tmp@
..
.
.
.\" --------------------------------------------------------------------
.\" SH SYNOPSIS
.\" --------------------------------------------------------------------
.
.B groff -m trace
.RI [ options\*[Ellipsis] ]
.RI [ files\*[Ellipsis] ]
.
.
.P
Elements in brackets denote optional arguments, and the ellipsis means
that there can be any number of arguments of this kind.
.
.
.\" --------------------------------------------------------------------
.SH DESCRIPTION
.\" --------------------------------------------------------------------
.
The
.I trace
macro package of
.BR groff (@MAN1EXT@)
can be a valuable tool for debugging documents written in the roff
formatting language.
.
A call stack trace is protocolled on standard error, that means, a
diagnostic message is emitted on entering and exiting of a macro call.
.
This greatly eases to track down an error in some macro.
.
.
.P
This tracing process is activated by specifying the groff or troff
command line option
.BR "-m\~trace" .
This works also with the
.BR groffer (@MAN1EXT@)
viewer program.
.
A finer control can be obtained by including the macro file within the
document by the groff macro call
.BR ".mso\~trace.tmac" .
Only macros that are defined after this line are traced.
.
.
.P
If some other macro package should be traced as well it must be specified
after
.BR "-m\~trace"
on the command line.
.
.
.P
The macro file
.B trace.tmac
is unusual because it does not contain any macros to be called by a
user.
.
Instead, the existing macro definition and appending facilities are
modified such that they display diagnostic messages.
.
.
.\" --------------------------------------------------------------------
.SH EXAMPLES
.\" --------------------------------------------------------------------
.
.P
In the following examples, a roff fragment is fed into groff via
standard input.
.
As we are only interested in the diagnostic messages (standard error)
on the terminal, the normal formatted output (standard output) is
redirected into the nirvana device
.IR /dev/null .
The resulting diagnostic messages are displayed directly below the
corresponding example.
.
.
.\" --------------------------------------------------------------------
.SS "Command line option"
.
.P
.Shell_cmd "echo '."
.Shell_cmd+ ".de test_macro"
.Shell_cmd+ ".."
.Shell_cmd+ ".test_macro"
.Shell_cmd+ ".test_macro some dummy arguments"
.Shell_cmd+ "' | groff -m trace >/dev/null"
.P
.Example
*** de trace enter: test_macro
*** trace exit: test_macro
*** de trace enter: test_macro "some" "dummy" "arguments"
*** trace exit: test_macro "some" "dummy" "arguments"
./Example
.
.P
The entry and the exit of each macro call is displayed on the terminal
(standard output) \[em] together with the arguments (if any).
.
.
.\" --------------------------------------------------------------------
.SS "Nested macro calls"
.
.P
.Shell_cmd "echo '."
.Shell_cmd+ ".de child"
.Shell_cmd+ ".."
.Shell_cmd+ ".de parent"
.Shell_cmd+ ".child"
.Shell_cmd+ ".."
.Shell_cmd+ ".parent"
.Shell_cmd+ "' | groff -m trace >/dev/null"
.P
.Example
*** de trace enter: parent
*** de trace enter: child
*** trace exit: child
*** trace exit: parent
./Example
.
.P
This shows that macro calls can be nested.
.
This powerful feature can help to tack down quite complex call stacks.
.
.
.\" --------------------------------------------------------------------
.SS "Activating with .mso"
.
.Shell_cmd "echo '."
.Shell_cmd+ ".de before"
.Shell_cmd+ ..
.Shell_cmd+ ".mso trace.tmac"
.Shell_cmd+ ".de after"
.Shell_cmd+ ..
.Shell_cmd+ .before
.Shell_cmd+ .after
.Shell_cmd+ .before
.Shell_cmd+ "' | groff >/dev/null"
.P
.Example
*** de trace enter: after
*** trace exit: after
./Example
.
.P
Here, the tracing is activated within the document, not by a command
line option.
.
As tracing was not active when macro
.I before
was defined, no call of this macro is protocolled; on the other hand,
the macro
.I after
is fully protocolled.
.
.
.\" --------------------------------------------------------------------
.SH FILES
.\" --------------------------------------------------------------------
.
The
.I trace
macros are kept in the file
.B trace.tmac
located in the
.IR "tmac directory" ;
see
.BR groff_tmac (@MAN5EXT@)
for details.
.
.
.\" --------------------------------------------------------------------
.SH ENVIRONMENT
.\" --------------------------------------------------------------------
.
.TP
.Env_var $GROFF_TMAC_PATH
A colon-separated list of additional tmac directories in which to
search for macro files; see
.BR groff_tmac (@MAN5EXT@)
for details.
.
.
.\" --------------------------------------------------------------------
.SH AUTHOR
.\" --------------------------------------------------------------------
.
Copyright (C) 2002 Free Software Foundation, Inc.
.
.P
This document is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later.
.
You should have received a copy of the FDL on your system, it is also
available on-line at the
.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
.
.P
This document is part of
.IR groff ,
the GNU roff distribution.
.
It was written by
.MTO bwarken@mayn.de "Bernd Warken".
.
.
.\" --------------------------------------------------------------------
.SH "SEE ALSO"
.\" --------------------------------------------------------------------
.
.TP
.BR groff (@MAN1EXT@)
An overview of the groff system.
.
.
.TP
.BR troff (@MAN1EXT@)
For details on option
.BR -m .
.
.
.TP
.BR groffer (@MAN1EXT@)
A viewer program for all kinds of roff documents.
.
.
.TP
.BR groff_tmac (@MAN5EXT@)
A general description of groff macro packages.
.
.
.TP
.BR groff (@MAN7EXT@)
A short reference for the groff formatting language.
.
.
.P
A complete reference for all parts of the groff system is found in the
groff
.BR info (1)
file.
.
.
.\" Local Variables:
.\" mode: nroff
.\" End: