/usr/share/doc/texinfo/html/Invoking-Macros.html

<html lang="en">
<head>
<title>Invoking Macros - GNU Texinfo 4.13</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Texinfo 4.13">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Defining-New-Texinfo-Commands.html#Defining-New-Texinfo-Commands" title="Defining New Texinfo Commands">
<link rel="prev" href="Defining-Macros.html#Defining-Macros" title="Defining Macros">
<link rel="next" href="Macro-Details.html#Macro-Details" title="Macro Details">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This manual is for GNU Texinfo (version 4.13, 18 September 2008),
a documentation system that can produce both online information and a
printed manual from a single source.

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover Texts
     being ``A GNU Manual'', and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
     this GNU Manual.  Buying copies from GNU Press supports the FSF in
     developing GNU and promoting software freedom.''
  -->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Invoking-Macros"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Macro-Details.html#Macro-Details">Macro Details</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Defining-Macros.html#Defining-Macros">Defining Macros</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Defining-New-Texinfo-Commands.html#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a>
<hr>
</div>

<h3 class="section">19.2 Invoking Macros</h3>

<p><a name="index-Invoking-macros-1080"></a><a name="index-Expanding-macros-1081"></a><a name="index-Running-macros-1082"></a><a name="index-Macro-invocation-1083"></a>
After a macro is defined (see the previous section), you can use
(<dfn>invoke</dfn>) it in your document like this:

<pre class="example">     @<var>macroname</var> {<var>arg1</var>, <var>arg2</var>, ...}
</pre>
  <p class="noindent">and the result will be just as if you typed the body of
<var>macroname</var> at that spot.  For example:

<pre class="example">     @macro foo {p, q}
     Together: \p\ &amp; \q\.
     @end macro
     @foo{a, b}
</pre>
  <p class="noindent">produces:

<pre class="display">     Together: a &amp; b.
</pre>
  <p><a name="index-Backslash_002c-and-macros-1084"></a>Thus, the arguments and parameters are separated by commas and delimited
by braces; any whitespace after (but not before) a comma is ignored. 
The braces are required in the invocation (but not the definition), even
when the macro takes no arguments, consistent with all other Texinfo
commands.  For example:

<pre class="example">     @macro argless {}
     No arguments here.
     @end macro
     @argless{}
</pre>
  <p class="noindent">produces:

<pre class="display">     No arguments here.
</pre>
  <p><a name="index-Comma_002c-in-macro-arguments-1085"></a>Passing strings containing commas as macro arguments requires special
care, since they should be properly <dfn>quoted</dfn> to prevent
<samp><span class="command">makeinfo</span></samp> from confusing them with argument separators.  To
manually quote a comma, prepend it with a backslash character, like
this: <code>\,</code>.  Alternatively, use the <code>@comma</code> command
(see <a href="Inserting-a-Comma.html#Inserting-a-Comma">Inserting a Comma</a>).  However, to facilitate use of macros,
<samp><span class="command">makeinfo</span></samp> implements a set of rules called <dfn>automatic
quoting</dfn>:

     <ol type=1 start=1>
<li>If a macro takes only one argument, all commas in its invocation
are quoted by default.  For example:

     <pre class="example">          @macro FIXME{text}
          @strong{FIXME: \text\}
          @end macro
          
          @FIXME{A nice feature, though it can be dangerous.}
</pre>
     <p class="noindent">will produce the following output

     <pre class="example">          <strong>FIXME: A nice feature, though it can be dangerous.</strong>
</pre>
     <p>And indeed, it can.  Namely, <samp><span class="command">makeinfo</span></samp>
does not control number of arguments passed to one-argument
macros, so be careful when you invoke them.

     <li>If a macro invocation includes another command (including a
recursive invocation of itself), any commas in the nested command
invocation(s) are quoted by default.  For example, in

     <pre class="example">          @say{@strong{Yes, I do}, person one}
</pre>
     <p>the comma after &lsquo;<samp><span class="samp">Yes</span></samp>&rsquo; is implicitly quoted.  Here's another
example, with a recursive macro:

     <pre class="example">          @rmacro cat{a,b}
          \a\\b\
          @end rmacro
          
          @cat{@cat{foo, bar}, baz}
</pre>
     <p class="noindent">will produce the string &lsquo;<samp><span class="samp">foobarbaz</span></samp>&rsquo;.

     <li>Otherwise, a comma should be explicitly quoted, as above, to be
treated as a part of an argument.
       </ol>

  <p><a name="index-Braces_002c-in-macro-arguments-1086"></a>Other characters that need to be quoted in macro arguments are
curly braces and backslash.  For example

<pre class="example">     @<var>macname</var> {\\\{\}\,}
</pre>
  <p class="noindent">will pass the (almost certainly error-producing) argument
&lsquo;<samp><span class="samp">\{},</span></samp>&rsquo; to <var>macname</var>.  However, commas in parameters, even
if escaped by a backslash, might cause trouble in TeX.

  <p>If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument.  For example:

<pre class="example">     @macro bar {p}
     Twice: \p\ &amp; \p\.
     @end macro
     @bar aah
</pre>
  <p class="noindent">produces:

<!-- Sorry for cheating, but let's not require macros to process the manual. -->
<pre class="display">     Twice: aah &amp; aah.
</pre>
  <p>If the macro is defined to take a single argument, and is invoked with
braces, the braced text is passed as the argument, regardless of
commas.  For example:

<pre class="example">     @macro bar {p}
     Twice: \p\ &amp; \p\.
     @end macro
     @bar{a,b}
</pre>
  <p class="noindent">produces:

<pre class="display">     Twice: a,b &amp; a,b.
</pre>
  </body></html>
texinfo-doc-nonfree 4.13a-1 / usr / share / doc / texinfo / html / Invoking-Macros.html
