From 1a786966a47d165c2a636742127fc0b676bd51ef Mon Sep 17 00:00:00 2001 From: esr Date: Sun, 4 Feb 2007 00:21:53 +0000 Subject: Adapted to use .SY/.OP/.YS, but this time with a proper Ellipsis string and without macro name shortening. --- tmac/groff_trace.man | 376 +++++++-------------------------------------------- 1 file changed, 47 insertions(+), 329 deletions(-) (limited to 'tmac/groff_trace.man') diff --git a/tmac/groff_trace.man b/tmac/groff_trace.man index bfcbd6f9..787ba906 100644 --- a/tmac/groff_trace.man +++ b/tmac/groff_trace.man @@ -1,15 +1,3 @@ -. -.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 @@ -31,287 +19,21 @@ 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@ -.. -. -. +.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_trace \- groff macro package trace.tmac .\" -------------------------------------------------------------------- .\" SH SYNOPSIS .\" -------------------------------------------------------------------- +.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. -. +.SY groff +.B -m trace +.OP options\*[Ellipsis] +.OP files\*[Ellipsis] +.YS . .\" -------------------------------------------------------------------- .SH DESCRIPTION @@ -380,20 +102,19 @@ 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 +.EX +\fIsh#\fP echo '. +> .de test_macro +> .. +> .test_macro +> .test_macro some dummy arguments +> ' | groff -m trace >/dev/null + *** 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 +.EE . .P The entry and the exit of each macro call is displayed on the terminal @@ -403,22 +124,21 @@ The entry and the exit of each macro call is displayed on the terminal .\" -------------------------------------------------------------------- .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 +.EX +\fIsh#\fP echo '. +> .de child +> .. +> .de parent +> .child +> .. +> .parent +> ' | groff -m trace >/dev/null + *** de trace enter: parent *** de trace enter: child *** trace exit: child *** trace exit: parent -./Example +.EE . .P This shows that macro calls can be nested. @@ -429,21 +149,21 @@ 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 +.EX +\fIsh#\fP echo '. +> .de before +> .. +> .mso trace.tmac +> .de after +> .. +> .before +> .after +> .before +> ' | groff >/dev/null + *** de trace enter: after *** trace exit: after -./Example +.EE . .P Here, the tracing is activated within the document, not by a command @@ -472,9 +192,9 @@ to prevent too early expansion of the backslash. For example, this macro call . .P -.Example +.EX \&.foo \e\e\e\en[bar] -./Example +.EE . .P normally passes `\e\en[bar]' to macro `.foo', but with the redefined @@ -488,9 +208,9 @@ escape which is an escape character not interpreted in copy mode, for example . .P -.Example +.EX \&.foo \eEn[bar] -./Example +.EE . . .\" -------------------------------------------------------------------- @@ -513,7 +233,7 @@ for details. .\" -------------------------------------------------------------------- . .TP -.Env_var $GROFF_TMAC_PATH +.B $GROFF_TMAC_PATH A colon-separated list of additional tmac directories in which to search for macro files; see .BR groff_tmac (@MAN5EXT@) @@ -579,8 +299,6 @@ groff .BR info (1) file. . -.cp \n[groff_trace_C] -. .\" Local Variables: .\" mode: nroff .\" End: -- cgit v1.2.1