19.3 Macro Details and Caveats

Due to unavoidable limitations, certain macro-related constructs cause problems with TeX. If you get macro-related errors when producing the printed version of a manual, try expanding the macros with makeinfo by invoking texi2dvi with the ‘-E’ option (see section Format with texi2dvi).

• As mentioned earlier, macro names must consist entirely of letters.
• It is not advisable to redefine any TeX primitive, plain, or Texinfo command name as a macro. Unfortunately this is a very large set of names, and the possible resulting errors are unpredictable.
• All macros are expanded inside at least one TeX group. This means that @set and other such commands have no effect inside a macro.
• Commas in macro arguments, even if escaped by a backslash, don't always work.
• Macro arguments cannot cross lines.
• It is (usually) best to avoid comments inside macro definitions, but see the next item.
• Macros containing a command which must be on a line by itself, such as a conditional, cannot be invoked in the middle of a line. In general, the interaction of newlines in the macro definitions and invocations depends on the precise commands and context. You may be able to work around some problems with judicious use of @c. Suppose you define a macro that is always intended to be used on a line by itself:

  @macro linemac @cindex whatever @c @end macro ... foo @linemac bar

  Without the @c, there will be an unwanted blank line between the ‘@cindex whatever’ and the ‘bar’ (one newline comes from the macro definition, one from after the invocation), causing a paragraph break.

  On the other hand, you wouldn't want the @c if the macro was sometimes invoked in the middle of a line (the text after the invocation would be treated as a comment).

• In general, you can't arbitrarily substitute a macro call for Texinfo command arguments, even when the text is the same. It might work with some commands, it fails with others. Best not to do it at all. For instance, this fails:

  @macro offmacro off @end macro @headings @offmacro

  You would expect this to be equivalent to @headings off, but for TeXnical reasons, it fails with a mysterious error message (Paragraph ended before @headings was complete).

• Macros cannot define macros in the natural way. To do this, you must use conditionals and raw TeX. For example:

  @ifnottex @macro ctor {name, arg} @macro \name\ something involving \arg\ somehow @end macro @end macro @end ifnottex @tex \gdef\ctor#1{\ctorx#1,} \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}} @end tex

The makeinfo implementation also has limitations:

• @verbatim and macros do not mix; for instance, you can't start a verbatim block inside a macro and end it outside. (See section @verbatim: Literal Text.) Starting any environment inside a macro and ending it outside may or may not work, for that matter.
• Macros that completely define macros are ok, but it's not possible to have incorrectly nested macro definitions. That is, @macro and @end macro (likewise for @rmacro) must be correctly paired. For example, you cannot start a macro definition within a macro, and then end the nested definition outside the macro.
• @rmacro is a kludge.

One more limitation is common to both implementations: white space is ignored at the beginnings of lines.

Future major revisions of Texinfo may ease some of these limitations (by introducing a new macro syntax).