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

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU Texinfo (version 5.2, 26 September 2013),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010, 2011, 2012, 2013 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 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 have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Texinfo 5.2: Defining Macros</title>

<meta name="description" content="GNU Texinfo 5.2: Defining Macros">
<meta name="keywords" content="GNU Texinfo 5.2: Defining Macros">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Command-and-Variable-Index.html#Command-and-Variable-Index" 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#Defining-New-Texinfo-Commands" rel="up" title="Defining New Texinfo Commands">
<link href="Invoking-Macros.html#Invoking-Macros" rel="next" title="Invoking Macros">
<link href="Defining-New-Texinfo-Commands.html#Defining-New-Texinfo-Commands" rel="previous" title="Defining New Texinfo Commands">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {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}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Defining-Macros"></a>
<div class="header">
<p>
Next: <a href="Invoking-Macros.html#Invoking-Macros" accesskey="n" rel="next">Invoking Macros</a>, Up: <a href="Defining-New-Texinfo-Commands.html#Defining-New-Texinfo-Commands" accesskey="u" rel="up">Defining New Texinfo Commands</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Defining-Macros-1"></a>
<h3 class="section">19.1 Defining Macros</h3>
<a name="index-Defining-macros"></a>
<a name="index-Macro-definitions_002c-Texinfo"></a>

<a name="index-macro"></a>
<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>, &hellip;}
<var>text</var> &hellip; \<var>param1</var>\ &hellip;
@end macro
</pre></div>

<p>The <em>parameters</em> <var>param1</var>, <var>param2</var>, &hellip; correspond to
arguments supplied when the macro is subsequently used in the document
(described in the next section).
</p>
<a name="index-Macro-names_002c-valid-characters-in"></a>
<a name="index-Names-of-macros_002c-valid-characters-of"></a>
<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) &lsquo;<samp>-</samp>&rsquo;.  The &lsquo;<samp>_</samp>&rsquo; character
is excluded so that macros can be called inside <code>@math</code> without
a following space (see <a href="Inserting-Math.html#Inserting-Math">Inserting Math</a>).
</p>
<p>If a macro needs no parameters, you can define it either with an empty
list (&lsquo;<samp>@macro foo {}</samp>&rsquo;) or with no braces at all (&lsquo;<samp>@macro
foo</samp>&rsquo;).
</p>
<a name="index-Body-of-a-macro"></a>
<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>
<a name="index-Parameters-to-macros"></a>
<p>In the macro body, instances of a parameter name surrounded by
backslashes, as in &lsquo;<samp>\<var>param1</var>\</samp>&rsquo; 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>
<a name="index-Backslash-in-macros"></a>
<p>To get a single &lsquo;<samp>\</samp>&rsquo; in the macro expansion, use &lsquo;<samp>\\</samp>&rsquo;.  Any
other use of &lsquo;<samp>\</samp>&rsquo; in the body yields a warning.
</p>
<a name="index-Spaces-in-macros"></a>
<a name="index-Whitespace-in-macros"></a>
<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.  However, there are still undesirable and unpredictable
interactions between newlines, macros, and commands which are
line-delimited, as warned about below (see <a href="Macro-Details.html#Macro-Details">Macro Details</a>).
</p>
<a name="index-Recursive-macro-invocations"></a>
<a name="index-rmacro"></a>
<p>To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with &lsquo;<samp>@rmacro</samp>&rsquo;, like this:
</p>
<div class="example">
<pre class="example">@rmacro rmac {arg}
a\arg\b
@end rmacro
&hellip;
@rmac{1@rmac{text}2}
</pre></div>

<p>This produces the output &lsquo;a1atextb2b&rsquo;.  With &lsquo;<samp>@macro</samp>&rsquo; instead of
&lsquo;<samp>@rmacro</samp>&rsquo;, an error message is given.
</p>
<a name="index-unmacro"></a>
<a name="index-Macros_002c-undefining"></a>
<a name="index-Undefining-macros"></a>
<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>


<hr>
<div class="header">
<p>
Next: <a href="Invoking-Macros.html#Invoking-Macros" accesskey="n" rel="next">Invoking Macros</a>, Up: <a href="Defining-New-Texinfo-Commands.html#Defining-New-Texinfo-Commands" accesskey="u" rel="up">Defining New Texinfo Commands</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
texinfo-doc-nonfree 5.2.0-1 / usr / share / doc / texinfo / html / Defining-Macros.html
