head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.1 netbsd-11-0-RC3:1.1.1.1 netbsd-11-0-RC2:1.1.1.1 netbsd-11-0-RC1:1.1.1.1 perseant-exfatfs-base-20250801:1.1.1.1 netbsd-11:1.1.1.1.0.30 netbsd-11-base:1.1.1.1 netbsd-10-1-RELEASE:1.1.1.1 perseant-exfatfs-base-20240630:1.1.1.1 perseant-exfatfs:1.1.1.1.0.28 perseant-exfatfs-base:1.1.1.1 netbsd-8-3-RELEASE:1.1.1.1 netbsd-9-4-RELEASE:1.1.1.1 netbsd-10-0-RELEASE:1.1.1.1 netbsd-10-0-RC6:1.1.1.1 netbsd-10-0-RC5:1.1.1.1 netbsd-10-0-RC4:1.1.1.1 netbsd-10-0-RC3:1.1.1.1 netbsd-10-0-RC2:1.1.1.1 netbsd-10-0-RC1:1.1.1.1 netbsd-10:1.1.1.1.0.26 netbsd-10-base:1.1.1.1 netbsd-9-3-RELEASE:1.1.1.1 cjep_sun2x-base1:1.1.1.1 cjep_sun2x:1.1.1.1.0.24 cjep_sun2x-base:1.1.1.1 cjep_staticlib_x-base1:1.1.1.1 netbsd-9-2-RELEASE:1.1.1.1 cjep_staticlib_x:1.1.1.1.0.22 cjep_staticlib_x-base:1.1.1.1 netbsd-9-1-RELEASE:1.1.1.1 phil-wifi-20200421:1.1.1.1 phil-wifi-20200411:1.1.1.1 is-mlppp:1.1.1.1.0.20 is-mlppp-base:1.1.1.1 phil-wifi-20200406:1.1.1.1 netbsd-8-2-RELEASE:1.1.1.1 netbsd-9-0-RELEASE:1.1.1.1 netbsd-9-0-RC2:1.1.1.1 netbsd-9-0-RC1:1.1.1.1 phil-wifi-20191119:1.1.1.1 netbsd-9:1.1.1.1.0.18 netbsd-9-base:1.1.1.1 phil-wifi-20190609:1.1.1.1 netbsd-8-1-RELEASE:1.1.1.1 netbsd-8-1-RC1:1.1.1.1 pgoyette-compat-merge-20190127:1.1.1.1 pgoyette-compat-20190127:1.1.1.1 pgoyette-compat-20190118:1.1.1.1 pgoyette-compat-1226:1.1.1.1 pgoyette-compat-1126:1.1.1.1 pgoyette-compat-1020:1.1.1.1 pgoyette-compat-0930:1.1.1.1 pgoyette-compat-0906:1.1.1.1 pgoyette-compat-0728:1.1.1.1 netbsd-8-0-RELEASE:1.1.1.1 phil-wifi:1.1.1.1.0.16 phil-wifi-base:1.1.1.1 pgoyette-compat-0625:1.1.1.1 netbsd-8-0-RC2:1.1.1.1 pgoyette-compat-0521:1.1.1.1 pgoyette-compat-0502:1.1.1.1 pgoyette-compat-0422:1.1.1.1 netbsd-8-0-RC1:1.1.1.1 pgoyette-compat-0415:1.1.1.1 pgoyette-compat-0407:1.1.1.1 pgoyette-compat-0330:1.1.1.1 pgoyette-compat-0322:1.1.1.1 pgoyette-compat-0315:1.1.1.1 pgoyette-compat:1.1.1.1.0.14 pgoyette-compat-base:1.1.1.1 matt-nb8-mediatek:1.1.1.1.0.12 matt-nb8-mediatek-base:1.1.1.1 perseant-stdc-iso10646:1.1.1.1.0.10 perseant-stdc-iso10646-base:1.1.1.1 netbsd-8:1.1.1.1.0.8 netbsd-8-base:1.1.1.1 prg-localcount2-base3:1.1.1.1 prg-localcount2-base2:1.1.1.1 prg-localcount2-base1:1.1.1.1 prg-localcount2:1.1.1.1.0.6 prg-localcount2-base:1.1.1.1 pgoyette-localcount-20170426:1.1.1.1 bouyer-socketcan-base1:1.1.1.1 pgoyette-localcount-20170320:1.1.1.1 bouyer-socketcan:1.1.1.1.0.4 bouyer-socketcan-base:1.1.1.1 pgoyette-localcount-20170107:1.1.1.1 pgoyette-localcount-20161104:1.1.1.1 localcount-20160914:1.1.1.1 pgoyette-localcount-20160806:1.1.1.1 pgoyette-localcount-20160726:1.1.1.1 pgoyette-localcount:1.1.1.1.0.2 pgoyette-localcount-base:1.1.1.1 groff-1-19-2:1.1.1.1 FSF:1.1.1; locks; strict; comment @.\" @; 1.1 date 2016.01.13.18.41.49; author christos; state Exp; branches 1.1.1.1; next ; commitid 3IfWnJaO3ZAcMNQy; 1.1.1.1 date 2016.01.13.18.41.49; author christos; state Exp; branches; next ; commitid 3IfWnJaO3ZAcMNQy; desc @@ 1.1 log @Initial revision @ text @. .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: /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 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 ( []) .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 (...) .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 ( [] ...) .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+ ( [] ...) .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 ( [ [] ...]) .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 (...) .c .c Treat the arguments as text, no matter how they look. .c .de Text . if (\\n[.$] == 0) \ . return . nop \)\\$*\) .. .c -------------------------------------------------------------------- .c .Topic ([]) .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: @ 1.1.1.1 log @Import groff 1.19.2 @ text @@