I have written some LaTeX macros, which I naively suppose get expanded at some
stage during the execution of latex... Unfortunately, there is something "wrong"
with them.  I DO NOT want anyone to "fix" my macros.

I DO want to be able to expand the macros so as to see what it is that they
expand to.   How (i.e., by what open source program) does one see the result
of macro expansion?

In case what I mean is something I am too ignorant to properly indicate, perhaps
the following analogy will clarify: I can invoke cpp (the C preprocessor) on a C
source file containing macros, and thereby see exactly what the C macros expand
to... so what is the analog for expanding a LaTeX macro?

---

Request for Question Clarification by maniac-ga on 06 Aug 2004 18:30 PDT

Hello Ignorant-ga,

Hmm. Are you familiar with how to embed TeX commands into your file?
If not, I should be able to walk you through that.

If so, try
  \tracingmacros=1
to enable macro expansion logging and
  \tracingmacros=0
to stop that logging. As an alternative,
  \tracingcommands=1 and \tracingcommands=0
will show all commands executed. \tracingcommands=2 will also show the
conditionals taken (and not taken).

All of this should go into the log file unless you also add
\tracingonline=1 which puts the tracing output to standard output.

Note also - these will likely show you a bunch of information from the
LaTeX style you are using as well.

If this helps, let me know so I can post a more complete answer. There
are even more tracing outputs available from TeX that I would
summarize.

  --Maniac

---

Clarification of Question by ignorant-ga on 09 Aug 2004 14:55 PDT

Yes it helps (though not quite what I expected)...  I'm looking forward
to your complete answer.

Thanks.

Hello Ignorant-ga,

From the TeXbook (I used the ninth edition)
  http://www-cs-faculty.stanford.edu/~knuth/abcde.html
  http://www.amazon.com/exec/obidos/tg/detail/-/0201134489?v=glance
there are a few references in the index related to "debugging". Most
of what I am referring to has double "dangerous bend" symbols which
were considered esoteric and required a month of TeX use before use.
I'll try to keep it simple so you don't get too deep. If you plan on
developing any LaTeX styles or complicated macros, I suggest getting a
copy of the book for reference. [or borrow from a local technical
library]

Section 20 - Definitions (also called Macros): introduces a number of
relevant concepts, including the precise rules that TeX macros follow.
For example, the general form of a definition is:
  \def<control sequence><parameter text>{<replacement text>}
so you can define something simple like:
  \def\a{\b}
which has no parameters and basically invokes \b whenever \a is seen
or something much more capable. To help diagnose complicated macros,
you can use
  \tracingmacros=1
to dump a series of lines in the log file representing:
 - the macro expansion
 - the list of parameters going into the macro
This is the essence of providing information related to macro
expansion as defined in TeX.

Section 22 - Alignment: goes into detail about how to align items
horizontally and vertically. As a debugging aid, it suggests adding
  \ddt
at the start and end of a template. This causes TeX to stop and
display the rest of the template. You can then use other TeX command
such as
  \showlists
to display relevant information.

Chapter 27 - Recovery from Errors: gives a number of hints including
several things to type when TeX stops including:
  H
to see the help message or
  <number>
to skip the next <number> tokens or
  I<phrase>
to insert <phrase> into the input at this point and proceed. Of
course, if you are in "batch mode" (common if using TeX as part of a
several step process) these will not work since TeX will try to go to
the end without stopping.

This section also includes the recommendation to
 "Remove all the things that do work, until you obtain the shortest
possible input file that fails in the same way as the original."
which is certainly a good suggestion for programming as well as TeX / LaTeX files.

If you get a message such as:
  TeX capacity exceeded, sorry.
like I did many years ago, you can try
  \tracingstats=1
to dump the size of 11 parameters at the end of the job or
  \tracingstats=2 (or more)
will dump that kind of data basically at the end of each page to help
isolate macros that take a lot of resources. I had to support some
extremely huge documents (thousands of pages) so we built our own
version of TeX with the relevant limits increased.

Several other tracing commands include:
 \tracingcommands - command trace
 \tracingparagraphs - displays decisions made for line breaks and spacing
 \tracingpages - displays page layout decisions [verbose]
 \tracinglostchars - displays characters dropped because not in the current font
 \tracingoutput - displays data on each "box" output
 \tracingonline - directs tracing output to standard output
 \tracingall - turn on everything [extremely verbose]
 \pause - pauses after EVERY line of input
Setting to 0 turns each one off, setting to a non zero value turns it on.

There is also a note that not all of these may be implemented in your
version of TeX (for performance reasons). If so, you would have to
rebuild TeX.

There is also a comment in Appendix B suggesting you add help to your
error messages (if you generate any). A sequence like...
  \newhelp\helpout{your help message here}
  \errhelp=\helpout
  \errmessage{your error message here}
can help your users understand the macros you define.

If you need further information related to this - please use the
clarification request. Good luck with your work.
  --Maniac

Thanks again maniac!