texinfo: Macro Details

Defining New Texinfo Commands

@alias

Invoking Macros

Back to Software Index

19.3 Macro Details and Caveats
==============================

By design, macro expansion does not happen in the following contexts in
'makeinfo':

   * '@macro' and '@unmacro' lines;

   * '@if...' lines, including '@ifset' and similar;

   * '@set', '@clear', '@value';

   * '@clickstyle' lines;

   * '@end' lines.

Unfortunately, TeX may do some expansion in these situations, possibly
yielding errors.

  Also, quite a few macro-related constructs cause problems with TeX;
some of the caveats are listed below.  Thus, if you get macro-related
errors when producing the printed version of a manual, you might try
expanding the macros with 'makeinfo' by invoking 'texi2dvi' with the
'-E' option (Note: Format with texi2dvi).  Or, more reliably, eschew
Texinfo macros altogether and use a language designed for macro
processing, such as M4 (Note: External Macro Processors).

   * 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 large and
     open-ended set of names, and the possible resulting errors are
     unpredictable.

   * All macros are expanded inside at least one TeX group.

   * Macro arguments cannot cross lines.

   * 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.
     Similarly, macros containing line-oriented commands or text, such
     as '@example' environments, may behave unpredictably in TeX.

   * White space is ignored at the beginnings of lines.

   * Macros can't be reliably used in the argument to accent commands
     (Note: Inserting Accents).

   * The backslash escape for commas in macro arguments does not work;
     '@comma{}' must be used.

   * As a consequence, if a macro takes two or more arguments, and you
     want to pass an argument with the Texinfo command '@,' (to produce
     a cedilla, Note: Inserting Accents), you have to use '@value' or
     another work-around.  Otherwise, TeX takes the comma as separating
     the arguments.  Example:

          @macro mactwo{argfirst, argsecond}
          \argfirst\+\argsecond\.
          @end macro
          @set fc Fran@,cois
          @mactwo{@value{fc}}

     produces:

          Franc,ois+.

     The natural-seeming '@mactwo{Fran@,cois}' passes the two arguments
     'Fran@' and 'cois' to the macro, and nothing good results.  And, as
     just mentioned, although the comma can be escaped with a backslash
     for 'makeinfo' ('@\,'), that doesn't work in TeX, so there is no
     other solution.

   * It is usually best to avoid comments inside macro definitions, but
     see the next item.

   * In general, the interaction of newlines in the macro definitions
     and invocations depends on the precise commands and context,
     notwithstanding the previous statements.  You may be able to work
     around some problems with judicious use of '@c'.  Suppose you
     define a macro that is always used on a line by itself:

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

     Without the '@c', there will be a unwanted blank line between the
     '@cindex whatever' and the 'bar' (one newline comes from the macro
     definition, one from after the invocation), causing an unwanted
     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 (or '@value')
     call for Texinfo command arguments, even when the text is the same.
     Texinfo is not M4 (or even plain TeX).  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

     This looks equivalent to '@headings off', but for TeXnical reasons,
     it fails with a mysterious error message (namely, '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 the following limitations (by
design):

   * '@verbatim' and macros do not mix; for instance, you can't start a
     verbatim block inside a macro and end it outside (Note:
     @verbatim).  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 incompletely 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 that nested definition outside the macro.

  In the 'makeinfo' implementation before Texinfo 5.0, ends of lines
from expansion of an '@macro' definition did not end an @-command
line-delimited argument ('@chapter', '@center', etc.).  This is no
longer the case.  For example:

     @macro twolines{}
     aaa
     bbb
     @end macro
     @center @twolines{}

  In the current 'makeinfo', this is equivalent to:

     @center aaa
     bbb

with just 'aaa' as the argument to '@center'.  In the earlier
implementation, it would have been parsed as this:

     @center aaa bbb