* 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.

1 files changed, 202 insertions, 209 deletions

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
 .