* tmac/trace.tmac: Much improved.

(trace-full): New register to be set on the command line; it
controls whether number and string register assignments get traced
also.
(!!c): New macro for comments.
(rm): New traced macro.
(de, de1, am, am1): Use \\[xxx]\\ calling method to pass \$0 to
`!!xxx'; this makes doc.tmac completely traceable.
Trace call of .de and friends also.

* tmac/groff_tmac.man, NEWS: Update.

4 files changed, 244 insertions, 227 deletions

diff --git a/ChangeLog b/ChangeLog
index 973cd237..329bc2b8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2008-10-09  Werner LEMBERG  <wl@gnu.org>
+
+	* tmac/trace.tmac: Much improved.
+	(trace-full): New register to be set on the command line; it
+	controls whether number and string register assignments get traced
+	also.
+	(!!c): New macro for comments.
+	(rm): New traced macro.
+	(de, de1, am, am1): Use \\[xxx]\\ calling method to pass \$0 to
+	`!!xxx'; this makes doc.tmac completely traceable.
+	Trace call of .de and friends also.
+
+	* tmac/groff_tmac.man, NEWS: Update.
+
 2008-09-30  Werner LEMBERG  <wl@gnu.org>
 
 	Restore behaviour of \$0 if a macro is called with string syntax
diff --git a/NEWS b/NEWS
index db77e119..b68662ff 100644
--- a/NEWS
+++ b/NEWS
@@ -186,7 +186,8 @@ o A new macro `Dx' has been added to the mdoc package which identifies the
   DragonFly OS.
 
 o -mtrace has been considerably improved, now showing number and string
-  register assignments, among other things.
+  register assignments, among other things.  See the groff_trace man page
+  for details.
 
 o The PSPIC macro now works with all devices (producing a hollow
   rectangle on devices which don't support inclusion of PS images) and
diff --git a/tmac/groff_trace.man b/tmac/groff_trace.man
index 9404e52d..49632c6d 100644
--- a/tmac/groff_trace.man
+++ b/tmac/groff_trace.man
@@ -3,11 +3,11 @@ groff_trace.7
 
 File position: <groff-source>/tmac/groff_trace.man
 
-Last update: 20 Feb 2007
+Last update: 01 Oct 2008
 
 This file is part of groff, the GNU roff type-setting system.
 
-Copyright (C) 2002, 2006, 2007 Free Software Foundation, Inc.
+Copyright (C) 2002, 2006, 2007, 2008 Free Software Foundation, Inc.
 written by Bernd Warken.
 
 Permission is granted to copy, distribute and/or modify this document
@@ -28,9 +28,8 @@ FDL in the main directory of the groff source package.
 groff_trace \- groff macro package trace.tmac
 .
 .\" --------------------------------------------------------------------
-.\" SH SYNOPSIS
-.\" --------------------------------------------------------------------
 .SH SYNOPSIS
+.\" --------------------------------------------------------------------
 .
 .SY "groff \-m trace"
 .RI [ options
@@ -50,7 +49,7 @@ macro package of
 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
+A call stack trace is protocolled on standard error, this is, a
 diagnostic message is emitted on entering and exiting of a macro call.
 .
 This greatly eases to track down an error in some macro.
@@ -71,6 +70,13 @@ Only macros that are defined after this line are traced.
 .
 .
 .P
+If command line option
+.B \-r\ trace-full=1
+is given (or if this register is set in the document), number and string
+register assignments together with some other requests are traced also.
+.
+.
+.P
 If some other macro package should be traced as well it must be specified
 after
 .B \-m\ trace
@@ -96,7 +102,7 @@ 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
+redirected to the nirvana device
 .IR /dev/null .
 The resulting diagnostic messages are displayed directly below the
 corresponding example.
@@ -116,10 +122,11 @@ Example:
 > .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"
+*** .de test_macro
+*** de trace enter: .test_macro
+*** trace exit: .test_macro
+*** de trace enter: .test_macro "some" "dummy" "arguments"
+*** trace exit: .test_macro "some" "dummy" "arguments"
 .EE
 .RE
 .
@@ -144,10 +151,12 @@ Example:
 > .parent
 > ' | groff -m trace >/dev/null
 
-*** de trace enter: parent
-*** de trace enter: child
-*** trace exit: child
-*** trace exit: parent
+*** .de child
+*** .de parent
+*** de trace enter: .parent
+ *** de trace enter: .child
+ *** trace exit: .child
+*** trace exit: .parent
 .EE
 .RE
 .
@@ -175,8 +184,8 @@ Example:
 > .before
 >  ' | groff >/dev/null
 
-*** de trace enter: after
-*** trace exit: after
+*** de trace enter: .after
+*** trace exit: .after
 .EE
 .RE
 .
@@ -259,7 +268,7 @@ for details.
 .SH AUTHOR
 .\" --------------------------------------------------------------------
 .
-Copyright (C) 2002, 2006, 2007 Free Software Foundation, Inc.
+Copyright (C) 2002, 2006, 2007, 2008 Free Software Foundation, Inc.
 .
 .P
 This document is distributed under the terms of the FDL (GNU Free
diff --git a/tmac/trace.tmac b/tmac/trace.tmac
index 67e56410..caa41eef 100644
--- a/tmac/trace.tmac
+++ b/tmac/trace.tmac
@@ -26,6 +26,18 @@
 .\"
 .
 .
+.\" Tracing within groff means replacing the original macros or requests
+.\" with special versions which act as wrappers to emit tracing information.
+.\" A natural consequence of creating such wrappers is that arguments must
+.\" be expanded once more.  In most cases it doesn't matter, however,
+.\" sometimes it makes a difference.
+.\"
+.\" To limit side effects, only macros are traced by default, together
+.\" with some requests like `.return' which don't take (user) arguments.
+.\" If you want more tracing, especially of number and string register
+.\" assignments, add the `-r trace-full=1' command line option.
+.
+.
 .\" Regarding the usage of `.do': All lines of macros which should
 .\" work in compatibility mode must be protected if they contain
 .\" GNU troff extensions and are defined with `.de'.  Example: `.ds',
@@ -44,75 +56,159 @@
 .de !!c
 ..
 .
+.
 .eo
 .
-.rn nr !!nr
+.rn return !!return
 .
-.de nr
-.  do ecs
-.  ec
-.  do !!nr \$*
-.  do tm1 "\*[!!!sp]*** .nr \$* (-> \n[\$1])
-.  do ecr
+.de1 return
+.  tm1 "\*[!!!sp]*** return
+.  !!return twice
 ..
 .
-.rn ds !!ds
-.rn ds1 !!ds1
-.rn as !!as
-.rn as1 !!as1
+.ec
 .
-.de ds
-.  do ecs
-.  ec
-.  do tm1 "\*[!!!sp]*** .ds \$^
-.  do !!ds \$^\"
-.  do ecr
-..
+.ie r trace-full \{\
+.  eo
+.
+.  rn nr !!nr
+.
+.  de nr
+.    do ecs
+.    ec
+.    do !!nr \$*
+.    do tm1 "\*[!!!sp]*** .nr \$* (-> \n[\$1])
+.    do ecr
+.  .
+.
+.  rn ds !!ds
+.  rn ds1 !!ds1
+.  rn as !!as
+.  rn as1 !!as1
+.
+.  de ds
+.    do ecs
+.    ec
+.    do tm1 "\*[!!!sp]*** .ds \$^
+.    do !!ds \$^\"
+.    do ecr
+.  .
+.
+.  de1 ds1
+.    ecs
+.    ec
+.    tm1 "\*[!!!sp]*** .ds1 \$^
+.    !!ds1 \$^\"
+.    ecr
+.  .
+.
+.  de as
+.    do ecs
+.    ec
+.    do tm1 "\*[!!!sp]*** .as \$^
+.    do !!as \$^\"
+.    do ecr
+.  .
+.
+.  de1 as1
+.    ecs
+.    ec
+.    tm1 "\*[!!!sp]*** .as1 \$^
+.    !!as1 \$^\"
+.    ecr
+.  .
+.
+.  rn substring !!substring
+.
+.  de1 substring
+.    ecs
+.    ec
+.    !!substring \$*
+.    tm1 "\*[!!!sp]*** .substring \$* (-> `\*[\$1]')
+.    ecr
+.  .
+.
+.  rn so !!so
+.
+.  de so
+.    do ecs
+.    ec
+.    do tm1 "\*[!!!sp]*** .so \$* {
+.    do !!as !!!sp " \"
+.    do ecr
+.    do !!so \$*
+.    do ecs
+.    ec
+.    do !!substring !!!sp 1
+.    do tm1 "\*[!!!sp]*** }
+.    do ecr
+.  .
 .
-.de1 ds1
-.  ecs
-.  ec
-.  tm1 "\*[!!!sp]*** .ds1 \$^
-.  !!ds1 \$^\"
-.  ecr
-..
+.  !!c We must use `.de' for the redefinition of .mso to avoid
+.  !!c side effects; for example, it might be called with
+.  !!c `.do mso ...'.
+.
+.  rn mso !!mso
+.
+.  de mso
+.    do ecs
+.    ec
+.    do tm1 "\*[!!!sp]*** .mso \$* {
+.    do !!as !!!sp " \"
+.    do ecr
+.    do !!mso \$*
+.    do ecs
+.    ec
+.    do !!substring !!!sp 1
+.    do tm1 "\*[!!!sp]*** }
+.    do ecr
+.  .
 .
-.de as
-.  do ecs
 .  ec
-.  do tm1 "\*[!!!sp]*** .as \$^
-.  do !!as \$^\"
-.  do ecr
-..
+.\}
+.el \{\
+.  als !!ds ds
+.  als !!as as
+.  als !!substring substring
+.\}
+.
+.
+.eo
 .
-.de1 as1
+.rn als !!als
+.
+.de1 als
 .  ecs
 .  ec
-.  tm1 "\*[!!!sp]*** .as1 \$^
-.  !!as1 \$^\"
+.  !!als \$*
+.  if d !!\$2 \
+.    !!als !!\$1 !!\$2
+.  tm1 "\*[!!!sp]*** .als \$*
 .  ecr
 ..
 .
-.rn substring !!substring
+.rn rm !!rm
 .
-.de1 substring
+.de1 rm
 .  ecs
 .  ec
-.  !!substring \$*
-.  tm1 "\*[!!!sp]*** .substring \$* (-> `\*[\$1]')
+.  !!rm \$*
+.  if d !!\$1 \
+.    !!rm !!\$1
+.  tm1 "\*[!!!sp]*** .rm \$*
 .  ecr
 ..
 .
-.rn als !!als
+.rn rn !!rn
 .
-.de1 als
-.  ecs
+.de rn
+.  do ecs
 .  ec
-.  !!als \$1 \$2
-.  if d !!\$2 \
-.    !!als !!\$1 !!\$2
-.  tm1 "\*[!!!sp]*** .als \$1 \$2
-.  ecr
+.  do !!rn \$*
+.  do if d !!\$1 \
+.    !!rn !!\$1 !!\$2
+.  do tm1 "\*[!!!sp]*** .rn \$*
+.  do ecr
 ..
 .
 .!!c Now the central tracing macros.  The redefined `de' macros
@@ -126,44 +222,32 @@
 .!!c The call to `dei' must be the last instruction in the macro
 .!!c (since it continues the definition of the macro to trace).
 .
-.rn de !!de
-.rn de1 !!de1
+.!!rn de !!de
+.!!rn de1 !!de1
 .
 .!!de de
 .  do ecs
 .  ec
 .  do !!de \$1
-.    do ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      do !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      do tm1 "\\*[!!!sp]*** de trace enter: \\*[!!!br]\\$0 \\$@
-.    el \
-.      do tm1 "\\*[!!!sp]*** de trace enter \$1: \\*[!!!br]\\$0 \\$@
+.    do ie \\n[.br] .do !!ds !!!br .\"
+.    el             .do !!ds !!!br '\"
+.    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** de trace enter: \\*[!!!br]\\$0 \\$@
+.    el            .do tm1 "\\*[!!!sp]*** de trace enter \$1: \\*[!!!br]\\$0 \\$@
 .    do !!as !!!sp " \"
-.    do ie \\n[.br] \
-.      do !!\\$0 \\$@
-.    el \
-'      do !!\\$0 \\$@
-.    do !!substring !!!sp 1
-.    do ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      do !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
-.    el \
-.      do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
-\..
 .
-.  do !!ds !!d1 !!\$1
-.  do !!ds !!d2 \$2
+.    do nop \\*[!!\\$0]\\
 .
-.  do !!de !!\$1
+.    do !!substring !!!sp 1
+.    do ie \\n[.br] .do !!ds !!!br .\"
+.    el             .do !!ds !!!br '\"
+.    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
+.    el            .do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 \..
-.  do !!als !!!!\$1 !!\$1
 .
+.  do tm1 "\*[!!!sp]*** .de \$*
+.
+.  do !!ds !!d1 !!\$1\"
+.  do !!ds !!d2 \$2\"
 .  do ecr
 .  do dei !!d1 !!d2
 ..
@@ -172,79 +256,55 @@
 .  ecs
 .  ec
 .  !!de1 \$1
-.    ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      tm1 "\\*[!!!sp]*** de1 trace enter: \\*[!!!br]\\$0 \\$@
-.    el \
-.      tm1 "\\*[!!!sp]*** de1 trace enter \$1: \\*[!!!br]\\$0 \\$@
+.    ie \\n[.br] .!!ds !!!br .\"
+.    el          .!!ds !!!br '\"
+.    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** de1 trace enter: \\*[!!!br]\\$0 \\$@
+.    el            .tm1 "\\*[!!!sp]*** de1 trace enter \$1: \\*[!!!br]\\$0 \\$@
 .    !!as !!!sp " \"
-.    ie \\n[.br] \
-.      !!\\$0 \\$@
-.    el \
-'      !!\\$0 \\$@
-.    !!substring !!!sp 1
-.    ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
-.    el \
-.      tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
-\..
 .
-.  !!ds !!d1 !!\$1
-.  !!ds !!d2 \$2
+.    nop \\*[!!\\$0]\\
 .
-.  !!de1 !!\$1
+.    !!substring !!!sp 1
+.    ie \\n[.br] .!!ds !!!br .\"
+.    el          .!!ds !!!br '\"
+.    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
+.    el            .tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 \..
-.  !!als !!!!\$1 !!\$1
 .
+.  tm1 "\*[!!!sp]*** .de1 \$*
+.
+.  !!ds !!d1 !!\$1\"
+.  !!ds !!d2 \$2\"
 .  ecr
 .  dei1 !!d1 !!d2
 ..
 .
-.rn am !!am
-.rn am1 !!am1
+.!!rn am !!am
+.!!rn am1 !!am1
 .
 .!!de am
 .  do ecs
 .  ec
 .  do !!de \$1
-.    do ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      do !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      do tm1 "\\*[!!!sp]*** am trace enter: \\*[!!!br]\\$0 \\$@
-.    el \
-.      do tm1 "\\*[!!!sp]*** am trace enter \$1: \\*[!!!br]\\$0 \\$@
+.    do ie \\n[.br] .do !!ds !!!br .\"
+.    el             .do !!ds !!!br '\"
+.    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** am trace enter: \\*[!!!br]\\$0 \\$@
+.    el            .do tm1 "\\*[!!!sp]*** am trace enter \$1: \\*[!!!br]\\$0 \\$@
 .    do !!as !!!sp " \"
-.    do ie \\n[.br] \
-.      do !!\\$0 \\$@
-.    el \
-'      do !!\\$0 \\$@
-.    do !!substring !!!sp 1
-.    do ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      do !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
-.    el \
-.      do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
-\..
 .
-.  do !!ds !!a1 !!\$1
-.  do !!ds !!a2 \$2
+.    do nop \\*[!!\\$0]\\
 .
-.  do !!de !!\$1
+.    do !!substring !!!sp 1
+.    do ie \\n[.br] .do !!ds !!!br .\"
+.    el             .do !!ds !!!br '\"
+.    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
+.    el            .do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 \..
-.  do !!als !!!!\$1 !!\$1
 .
+.  do tm1 "\*[!!!sp]*** .am \$*
+.
+.  do !!ds !!a1 !!\$1\"
+.  do !!ds !!a2 \$2\"
 .  do ecr
 .  do ami !!a1 !!a2
 ..
@@ -253,96 +313,29 @@
 .  ecs
 .  ec
 .  !!de1 \$1
-.    ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      tm1 "\\*[!!!sp]*** am1 trace enter: \\*[!!!br]\\$0 \\$@
-.    el \
-.      tm1 "\\*[!!!sp]*** am1 trace enter \$1: \\*[!!!br]\\$0 \\$@
+.    ie \\n[.br] .!!ds !!!br .\"
+.    el          .!!ds !!!br '\"
+.    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** am1 trace enter: \\*[!!!br]\\$0 \\$@
+.    el            .tm1 "\\*[!!!sp]*** am1 trace enter \$1: \\*[!!!br]\\$0 \\$@
 .    !!as !!!sp " \"
-.    ie \\n[.br] \
-.      !!\\$0 \\$@
-.    el \
-'      !!\\$0 \\$@
-.    !!substring !!!sp 1
-.    ie \\n[.br] \
-.      !!ds !!!br .\"
-.    el \
-.      !!ds !!!br '\"
-.    ie "\$1"\\$0" \
-.      tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
-.    el \
-.      tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
-\..
 .
-.  !!ds !!a1 !!\$1
-.  !!ds !!a2 \$2
+.    nop \\*[!!\\$0]\\
 .
-.  !!de1 !!\$1
+.    !!substring !!!sp 1
+.    ie \\n[.br] .!!ds !!!br .\"
+.    el          .!!ds !!!br '\"
+.    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
+.    el            .tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 \..
-.  !!als !!!!\$1 !!\$1
 .
+.  tm1 "\*[!!!sp]*** .am1 \$*
+.
+.  !!ds !!a1 !!\$1\"
+.  !!ds !!a2 \$2\"
 .  ecr
 .  ami1 !!a1 !!a2
 ..
 .
-.rn return !!return
-.
-.!!de1 return
-.  tm1 "\*[!!!sp]*** return
-.  !!return twice
-..
-.
-.rn so !!so
-.
-.!!de so
-.  do ecs
-.  ec
-.  do tm1 "\*[!!!sp]*** .so \$* {
-.  do !!as !!!sp " \"
-.  do ecr
-.  do !!so \$*
-.  do ecs
-.  ec
-.  do !!substring !!!sp 1
-.  do tm1 "\*[!!!sp]*** }
-.  do ecr
-..
-.
-.!!c We must use `.de' for the redefinition of .mso to avoid
-.!!c side effects; for example, it might be called with
-.!!c `.do mso ...'.
-.
-.rn mso !!mso
-.
-.!!de mso
-.  do ecs
-.  ec
-.  do tm1 "\*[!!!sp]*** .mso \$* {
-.  do !!as !!!sp " \"
-.  do ecr
-.  do !!mso \$*
-.  do ecs
-.  ec
-.  do !!substring !!!sp 1
-.  do tm1 "\*[!!!sp]*** }
-.  do ecr
-..
-.
-.
-.rn rn !!rn
-.
-.!!de rn
-.  do ecs
-.  ec
-.  do !!rn \$1 \$2
-.  do if d !!\$1 \
-.    !!rn !!\$1 !!\$2
-.  do tm1 "\*[!!!sp]*** .rn \$1 \$2
-.  do ecr
-..
 .
 .ec
 .