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