tmac/trace.tmac

   1 .\" trace.tmac
   2 .\"
   3 .\" Load this before a macro package that you want to trace.
   4 .\"
   5 .\"
   6 .\" Copyright (C) 1989, 1990, 1991, 1992, 2000, 2002, 2003, 2004, 2006,
   7 .\"               2007, 2008
   8 .\"   Free Software Foundation, Inc.
   9 .\"      Written by James Clark (jjc@jclark.com)
  10 .\"
  11 .\" This file is part of groff.
  12 .\"
  13 .\" groff is free software; you can redistribute it and/or modify it under
  14 .\" the terms of the GNU General Public License as published by the Free
  15 .\" Software Foundation; either version 2, or (at your option) any later
  16 .\" version.
  17 .\"
  18 .\" groff is distributed in the hope that it will be useful, but WITHOUT ANY
  19 .\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
  20 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21 .\" for more details.
  22 .\"
  23 .\" You should have received a copy of the GNU General Public License along
  24 .\" with groff; see the file COPYING.  If not, write to the Free Software
  25 .\" Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
  26 .\"
  27 .
  28 .
  29 .\" Tracing within groff means replacing the original macros or requests
  30 .\" with special versions which act as wrappers to emit tracing information.
  31 .\" A natural consequence of creating such wrappers is that arguments must
  32 .\" be expanded once more.  In most cases it doesn't matter, however,
  33 .\" sometimes it makes a difference.
  34 .\"
  35 .\" To limit side effects, only macros are traced by default, together
  36 .\" with some requests like `.return' which don't take (user) arguments.
  37 .\" If you want more tracing, especially of number and string register
  38 .\" assignments, add the `-r trace-full=1' command line option.
  39 .
  40 .
  41 .\" Regarding the usage of `.do': All lines of macros which should
  42 .\" work in compatibility mode must be protected if they contain
  43 .\" GNU troff extensions and are defined with `.de'.  Example: `.ds',
  44 .\" but not `.ds1', since the latter can't be called in compatibility
  45 .\" mode.
  46 .
  47 .
  48 .do if d !!!sp \
  49 .  nx
  50 .
  51 .nr _C \n(.C
  52 .cp 0
  53 .
  54 .ds !!!sp " \"
  55 .
  56 .de !!c
  57 ..
  58 .
  59 .
  60 .eo
  61 .
  62 .rn return !!return
  63 .
  64 .de1 return
  65 .  tm1 "\*[!!!sp]*** return
  66 .  !!return twice
  67 ..
  68 .
  69 .ec
  70 .
  71 .ie r trace-full \{\
  72 .  eo
  73 .
  74 .  rn nr !!nr
  75 .
  76 .  de nr
  77 .    do ecs
  78 .    ec
  79 .    do !!nr \$*
  80 .    do tm1 "\*[!!!sp]*** .nr \$* (-> \n[\$1])
  81 .    do ecr
  82 .  .
  83 .
  84 .  rn ds !!ds
  85 .  rn ds1 !!ds1
  86 .  rn as !!as
  87 .  rn as1 !!as1
  88 .
  89 .  de ds
  90 .    do ecs
  91 .    ec
  92 .    do tm1 "\*[!!!sp]*** .ds \$^
  93 .    do !!ds \$^\"
  94 .    do ecr
  95 .  .
  96 .
  97 .  de1 ds1
  98 .    ecs
  99 .    ec
 100 .    tm1 "\*[!!!sp]*** .ds1 \$^
 101 .    !!ds1 \$^\"
 102 .    ecr
 103 .  .
 104 .
 105 .  de as
 106 .    do ecs
 107 .    ec
 108 .    do tm1 "\*[!!!sp]*** .as \$^
 109 .    do !!as \$^\"
 110 .    do ecr
 111 .  .
 112 .
 113 .  de1 as1
 114 .    ecs
 115 .    ec
 116 .    tm1 "\*[!!!sp]*** .as1 \$^
 117 .    !!as1 \$^\"
 118 .    ecr
 119 .  .
 120 .
 121 .  rn substring !!substring
 122 .
 123 .  de1 substring
 124 .    ecs
 125 .    ec
 126 .    !!substring \$*
 127 .    tm1 "\*[!!!sp]*** .substring \$* (-> `\*[\$1]')
 128 .    ecr
 129 .  .
 130 .
 131 .  rn so !!so
 132 .
 133 .  de so
 134 .    do ecs
 135 .    ec
 136 .    do tm1 "\*[!!!sp]*** .so \$* {
 137 .    do !!as !!!sp " \"
 138 .    do ecr
 139 .    do !!so \$*
 140 .    do ecs
 141 .    ec
 142 .    do !!substring !!!sp 1
 143 .    do tm1 "\*[!!!sp]*** }
 144 .    do ecr
 145 .  .
 146 .
 147 .  !!c We must use `.de' for the redefinition of .mso to avoid
 148 .  !!c side effects; for example, it might be called with
 149 .  !!c `.do mso ...'.
 150 .
 151 .  rn mso !!mso
 152 .
 153 .  de mso
 154 .    do ecs
 155 .    ec
 156 .    do tm1 "\*[!!!sp]*** .mso \$* {
 157 .    do !!as !!!sp " \"
 158 .    do ecr
 159 .    do !!mso \$*
 160 .    do ecs
 161 .    ec
 162 .    do !!substring !!!sp 1
 163 .    do tm1 "\*[!!!sp]*** }
 164 .    do ecr
 165 .  .
 166 .
 167 .  ec
 168 .\}
 169 .el \{\
 170 .  als !!ds ds
 171 .  als !!as as
 172 .  als !!substring substring
 173 .\}
 174 .
 175 .
 176 .eo
 177 .
 178 .rn als !!als
 179 .
 180 .de1 als
 181 .  ecs
 182 .  ec
 183 .  !!als \$*
 184 .  if d !!\$2 \
 185 .    !!als !!\$1 !!\$2
 186 .  tm1 "\*[!!!sp]*** .als \$*
 187 .  ecr
 188 ..
 189 .
 190 .rn rm !!rm
 191 .
 192 .de1 rm
 193 .  ecs
 194 .  ec
 195 .  !!rm \$*
 196 .  if d !!\$1 \
 197 .    !!rm !!\$1
 198 .  tm1 "\*[!!!sp]*** .rm \$*
 199 .  ecr
 200 ..
 201 .
 202 .rn rn !!rn
 203 .
 204 .de rn
 205 .  do ecs
 206 .  ec
 207 .  do !!rn \$*
 208 .  do if d !!\$1 \
 209 .    !!rn !!\$1 !!\$2
 210 .  do tm1 "\*[!!!sp]*** .rn \$*
 211 .  do ecr
 212 ..
 213 .
 214 .!!c Now the central tracing macros.  The redefined `de' macros
 215 .!!c create wrapper macros `foo' which emit tracing messages
 216 .!!c before and after the call to the traced macro `!!foo'.
 217 .!!c
 218 .!!c Note that we define `!!foo' in advance so that an alias to
 219 .!!c `!!!!foo' is possible.  The latter occurs if `foo' is
 220 .!!c called as \\[foo].
 221 .!!c
 222 .!!c The call to `dei' must be the last instruction in the macro
 223 .!!c (since it continues the definition of the macro to trace).
 224 .
 225 .!!rn de !!de
 226 .!!rn de1 !!de1
 227 .
 228 .!!de de
 229 .  do ecs
 230 .  ec
 231 .  do !!de \$1
 232 .    do ie \\n[.br] .do !!ds !!!br .\"
 233 .    el             .do !!ds !!!br '\"
 234 .    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** de trace enter: \\*[!!!br]\\$0 \\$@
 235 .    el            .do tm1 "\\*[!!!sp]*** de trace enter \$1: \\*[!!!br]\\$0 \\$@
 236 .    do !!as !!!sp " \"
 237 .
 238 .    do nop \\*[!!\\$0]\\
 239 .
 240 .    do !!substring !!!sp 1
 241 .    do ie \\n[.br] .do !!ds !!!br .\"
 242 .    el             .do !!ds !!!br '\"
 243 .    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
 244 .    el            .do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 245 \..
 246 .
 247 .  do tm1 "\*[!!!sp]*** .de \$*
 248 .
 249 .  do !!ds !!d1 !!\$1\"
 250 .  do !!ds !!d2 \$2\"
 251 .  do ecr
 252 .  do dei !!d1 !!d2
 253 ..
 254 .
 255 .!!de1 de1
 256 .  ecs
 257 .  ec
 258 .  !!de1 \$1
 259 .    ie \\n[.br] .!!ds !!!br .\"
 260 .    el          .!!ds !!!br '\"
 261 .    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** de1 trace enter: \\*[!!!br]\\$0 \\$@
 262 .    el            .tm1 "\\*[!!!sp]*** de1 trace enter \$1: \\*[!!!br]\\$0 \\$@
 263 .    !!as !!!sp " \"
 264 .
 265 .    nop \\*[!!\\$0]\\
 266 .
 267 .    !!substring !!!sp 1
 268 .    ie \\n[.br] .!!ds !!!br .\"
 269 .    el          .!!ds !!!br '\"
 270 .    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
 271 .    el            .tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 272 \..
 273 .
 274 .  tm1 "\*[!!!sp]*** .de1 \$*
 275 .
 276 .  !!ds !!d1 !!\$1\"
 277 .  !!ds !!d2 \$2\"
 278 .  ecr
 279 .  dei1 !!d1 !!d2
 280 ..
 281 .
 282 .!!rn am !!am
 283 .!!rn am1 !!am1
 284 .
 285 .!!de am
 286 .  do ecs
 287 .  ec
 288 .  do !!de \$1
 289 .    do ie \\n[.br] .do !!ds !!!br .\"
 290 .    el             .do !!ds !!!br '\"
 291 .    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** am trace enter: \\*[!!!br]\\$0 \\$@
 292 .    el            .do tm1 "\\*[!!!sp]*** am trace enter \$1: \\*[!!!br]\\$0 \\$@
 293 .    do !!as !!!sp " \"
 294 .
 295 .    do nop \\*[!!\\$0]\\
 296 .
 297 .    do !!substring !!!sp 1
 298 .    do ie \\n[.br] .do !!ds !!!br .\"
 299 .    el             .do !!ds !!!br '\"
 300 .    ie "\$1"\\$0" .do tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
 301 .    el            .do tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 302 \..
 303 .
 304 .  do tm1 "\*[!!!sp]*** .am \$*
 305 .
 306 .  do !!ds !!a1 !!\$1\"
 307 .  do !!ds !!a2 \$2\"
 308 .  do ecr
 309 .  do ami !!a1 !!a2
 310 ..
 311 .
 312 .!!de1 am1
 313 .  ecs
 314 .  ec
 315 .  !!de1 \$1
 316 .    ie \\n[.br] .!!ds !!!br .\"
 317 .    el          .!!ds !!!br '\"
 318 .    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** am1 trace enter: \\*[!!!br]\\$0 \\$@
 319 .    el            .tm1 "\\*[!!!sp]*** am1 trace enter \$1: \\*[!!!br]\\$0 \\$@
 320 .    !!as !!!sp " \"
 321 .
 322 .    nop \\*[!!\\$0]\\
 323 .
 324 .    !!substring !!!sp 1
 325 .    ie \\n[.br] .!!ds !!!br .\"
 326 .    el          .!!ds !!!br '\"
 327 .    ie "\$1"\\$0" .tm1 "\\*[!!!sp]*** trace exit: \\*[!!!br]\\$0 \\$@
 328 .    el            .tm1 "\\*[!!!sp]*** trace exit \$1: \\*[!!!br]\\$0 \\$@
 329 \..
 330 .
 331 .  tm1 "\*[!!!sp]*** .am1 \$*
 332 .
 333 .  !!ds !!a1 !!\$1\"
 334 .  !!ds !!a2 \$2\"
 335 .  ecr
 336 .  ami1 !!a1 !!a2
 337 ..
 338 .
 339 .
 340 .ec
 341 .
 342 .cp \n(_C
 343 .
 344 .\" EOF