/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
- .
- .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
- .\" --------------------------------------------------------------------
- .
- .do nr groff_trace_C \n[.C]
- .cp 0
- .
- .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.
- .
- .cp \n[groff_trace_C]
- .
- .\" Local Variables:
- .\" mode: nroff
- .\" End: