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