JezK
Edit File: Defining-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>Defining Macros (GNU Texinfo 6.8)</title> <meta name="description" content="Defining Macros (GNU Texinfo 6.8)"> <meta name="keywords" content="Defining 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="Invoking-Macros.html" rel="next" title="Invoking 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="Defining-Macros"> <div class="header"> <p> Next: <a href="Invoking-Macros.html" accesskey="n" rel="next">Invoking 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="Defining-Macros-1"></span><h3 class="section">16.1 Defining Macros</h3> <span id="index-Defining-macros"></span> <span id="index-Macro-definitions_002c-Texinfo"></span> <span id="index-macro"></span> <p>You use the Texinfo <code>@macro</code> command to define a macro, like this: </p> <div class="example"> <pre class="example">@macro <var>macroname</var>{<var>param1</var>, <var>param2</var>, …} <var>text</var> … \<var>param1</var>\ … @end macro </pre></div> <p>The <em>parameters</em> <var>param1</var>, <var>param2</var>, … correspond to arguments supplied when the macro is subsequently used in the document (described in the next section). </p> <span id="index-Macro-names_002c-valid-characters-in"></span> <span id="index-Names-of-macros_002c-valid-characters-of"></span> <p>For a macro to work consistently with TeX, <var>macroname</var> must consist entirely of letters: no digits, hyphens, underscores, or other special characters. So, we recommend using only letters. However, <code>makeinfo</code> will accept anything consisting of alphanumerics, and (except as the first character) ‘<samp>-</samp>’. The ‘<samp>_</samp>’ character is excluded so that macros can be called inside <code>@math</code> without a following space (see <a href="Inserting-Math.html"><code>@math</code> and <code>@displaymath</code>: Formatting Mathematics</a>). </p> <p>If a macro needs no parameters, you can define it either with an empty list (‘<samp>@macro foo {}</samp>’) or with no braces at all (‘<samp>@macro foo</samp>’). </p> <span id="index-Body-of-a-macro"></span> <p>The definition or <em>body</em> of the macro can contain most Texinfo commands, including macro invocations. However, a macro definition that defines another macro does not work in TeX due to limitations in the design of <code>@macro</code>. </p> <span id="index-Parameters-to-macros"></span> <p>In the macro body, instances of a parameter name surrounded by backslashes, as in ‘<samp>\<var>param1</var>\</samp>’ in the example above, are replaced by the corresponding argument from the macro invocation. You can use parameter names any number of times in the body, including zero. </p> <span id="index-Backslash-in-macros"></span> <p>To get a single ‘<samp>\</samp>’ in the macro expansion, use ‘<samp>\\</samp>’. Any other use of ‘<samp>\</samp>’ in the body yields a warning. </p> <span id="index-Spaces-in-macros"></span> <span id="index-Whitespace-in-macros"></span> <p>The newline characters after the <code>@macro</code> line and before the <code>@end macro</code> line are ignored, that is, not included in the macro body. All other whitespace is treated according to the usual Texinfo rules. </p> <span id="index-Recursive-macro-invocations"></span> <span id="index-rmacro"></span> <p>To allow a macro to be used recursively, that is, in an argument to a call to itself, you must define it with ‘<samp>@rmacro</samp>’, like this: </p> <div class="example"> <pre class="example">@rmacro rmac {arg} a\arg\b @end rmacro … @rmac{1@rmac{text}2} </pre></div> <p>This produces the output ‘a1atextb2b’. With ‘<samp>@macro</samp>’ instead of ‘<samp>@rmacro</samp>’, an error message is given. </p> <span id="index-unmacro"></span> <span id="index-Macros_002c-undefining"></span> <span id="index-Undefining-macros"></span> <p>You can undefine a macro <var>foo</var> with <code>@unmacro <var>foo</var></code>. It is not an error to undefine a macro that is already undefined. For example: </p> <div class="example"> <pre class="example">@unmacro foo </pre></div> </div> <hr> <div class="header"> <p> Next: <a href="Invoking-Macros.html">Invoking 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>