JezK
Edit File: Invoking-Macros.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 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.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Invoking Macros (GNU Texinfo 6.8)</title> <meta name="description" content="Invoking Macros (GNU Texinfo 6.8)"> <meta name="keywords" content="Invoking Macros (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Defining-New-Texinfo-Commands.html" rel="up" title="Defining New Texinfo Commands"> <link href="Macro-Details.html" rel="next" title="Macro Details"> <link href="Defining-Macros.html" rel="prev" title="Defining Macros"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="section" id="Invoking-Macros"> <div class="header"> <p> Next: <a href="Macro-Details.html" accesskey="n" rel="next">Macro Details and Caveats</a>, Previous: <a href="Defining-Macros.html" accesskey="p" rel="prev">Defining Macros</a>, Up: <a href="Defining-New-Texinfo-Commands.html" accesskey="u" rel="up">Defining New Texinfo Commands</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="Invoking-Macros-1"></span><h3 class="section">16.2 Invoking Macros</h3> <span id="index-Invoking-macros"></span> <span id="index-Expanding-macros"></span> <span id="index-Running-macros"></span> <span id="index-Macro-invocation"></span> <p>After a macro is defined (see the previous section), you can <em>invoke</em> (use) it in your document like this: </p> <div class="example"> <pre class="example">@<var>macroname</var> {<var>arg1</var>, <var>arg2</var>, …} </pre></div> <p>and the result will be more or less as if you typed the body of <var>macroname</var> at that spot. For example: </p> <div class="example"> <pre class="example">@macro foo {p, q} Together: \p\ & \q\. @end macro @foo{a, b} </pre></div> <p>produces: </p> <div class="display"> <pre class="display">Together: a & b. </pre></div> <span id="index-Backslash_002c-and-macros"></span> <p>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 even when the macro takes no arguments, consistent with other Texinfo commands. For example: </p> <div class="example"> <pre class="example">@macro argless {} No arguments here. @end macro @argless{} </pre></div> <p>produces: </p> <div class="display"> <pre class="display">No arguments here. </pre></div> <span id="index-Comma_002c-in-macro-arguments"></span> <p>Passing macro arguments containing commas requires care, since commas also separate the arguments. To include a comma character in an argument, the most reliable method is to use the <code>@comma{}</code> command. For <code>makeinfo</code>, you can also prepend a backslash character, as in ‘<samp>\,</samp>’, but this does not work with TeX. </p> <span id="index-Automatic-quoting-of-commas-for-some-macros"></span> <span id="index-Quoting_002c-automatic-for-some-macros"></span> <p>It’s not always necessary to worry about commas. To facilitate use of macros, <code>makeinfo</code> implements two rules for <em>automatic quoting</em> in some circumstances: </p> <ol> <li> If a macro takes only one argument, all commas in its invocation are quoted by default. For example: <div class="example"> <pre class="example">@macro TRYME{text} @strong{TRYME: \text\} @end macro @TRYME{A nice feature, though it can be dangerous.} </pre></div> <p>will produce the following output </p> <div class="example"> <pre class="example"><strong>TRYME: A nice feature, though it can be dangerous.</strong> </pre></div> <p>And indeed, it can. Namely, <code>makeinfo</code> does not control the number of arguments passed to one-argument macros, so be careful when you invoke them. </p> </li><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 <div class="example"> <pre class="example">@say{@strong{Yes, I do}, person one} </pre></div> <p>the comma after ‘<samp>Yes</samp>’ is implicitly quoted. Here’s another example, with a recursive macro: </p> <div class="example"> <pre class="example">@rmacro cat{a,b} \a\\b\ @end rmacro @cat{@cat{foo, bar}, baz} </pre></div> <p>will produce the string ‘<samp>foobarbaz</samp>’. </p> </li><li> Otherwise, a comma should be explicitly quoted, as above, for it to be treated as a part of an argument. </li></ol> <span id="index-Backslash_002c-in-macro-arguments"></span> <span id="index-Braces_002c-in-macro-arguments"></span> <p>The backslash itself can be quoted in macro arguments with another backslash. For example: </p> <div class="example"> <pre class="example">@<var>macname</var> {\\bleh} </pre></div> <p>will pass the argument ‘<samp>\bleh</samp>’ to <var>macname</var>. </p> <p><code>makeinfo</code> also recognizes ‘<samp>\{</samp>’ and ‘<samp>\}</samp>’ sequences for curly braces, but these are not recognized by the implementation in TeX. There should, however, rarely be a need for these, as they are only needed when a macro argument contains unbalanced braces. </p> <p>If a macro is defined to take exactly one argument, it can be invoked without any braces, taking all of the line after the macro name as the argument. For example: </p> <div class="example"> <pre class="example">@macro bar {p} Twice: \p\ & \p\. @end macro @bar aah </pre></div> <p>produces: </p> <div class="display"> <pre class="display">Twice: aah & aah. </pre></div> <p>In these arguments, there is no escaping of special characters, so each ‘<samp>\</samp>’ stands for itself. </p> <p>If a macro is defined to take more than one argument, but is called with only one (in braces), the remaining arguments are set to the empty string, and no error is given. For example: </p> <div class="example"> <pre class="example">@macro addtwo {p, q} Both: \p\\q\. @end macro @addtwo{a} </pre></div> <p>produces simply: </p> <div class="display"> <pre class="display">Both: a. </pre></div> </div> <hr> <div class="header"> <p> Next: <a href="Macro-Details.html">Macro Details and Caveats</a>, Previous: <a href="Defining-Macros.html">Defining Macros</a>, Up: <a href="Defining-New-Texinfo-Commands.html">Defining New Texinfo Commands</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>