/usr/share/doc/texinfo/html/Invoking-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: Invoking Macros</title>

<meta name="description" content="GNU Texinfo 5.2: Invoking Macros">
<meta name="keywords" content="GNU Texinfo 5.2: Invoking 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="Macro-Details.html#Macro-Details" rel="next" title="Macro Details">
<link href="Defining-Macros.html#Defining-Macros" rel="previous" title="Defining Macros">
<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="Invoking-Macros"></a>
<div class="header">
<p>
Next: <a href="Macro-Details.html#Macro-Details" accesskey="n" rel="next">Macro Details</a>, Previous: <a href="Defining-Macros.html#Defining-Macros" accesskey="p" rel="previous">Defining 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="Invoking-Macros-1"></a>
<h3 class="section">19.2 Invoking Macros</h3>

<a name="index-Invoking-macros"></a>
<a name="index-Expanding-macros"></a>
<a name="index-Running-macros"></a>
<a name="index-Macro-invocation"></a>

<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>, &hellip;}
</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\ &amp; \q\.
@end macro
@foo{a, b}
</pre></div>

<p>produces:
</p>
<div class="display">
<pre class="display">Together: a &amp; b.
</pre></div>

<a name="index-Backslash_002c-and-macros"></a>
<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>

<a name="index-Comma_002c-in-macro-arguments"></a>
<p>Passing macro arguments containing commas requires special 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 &lsquo;<samp>\,</samp>&rsquo;, but this does not work with TeX.
</p>
<a name="index-Automatic-quoting-of-commas-for-some-macros"></a>
<a name="index-Quoting_002c-automatic-for-some-macros"></a>
<p>It&rsquo;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 &lsquo;<samp>Yes</samp>&rsquo; is implicitly quoted.  Here&rsquo;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 &lsquo;<samp>foobarbaz</samp>&rsquo;.
</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>

<a name="index-Braces_002c-in-macro-arguments"></a>
<a name="index-Backslash_002c-in-macro-arguments"></a>
<p>In addition to the comma, characters that need to be quoted in macro
arguments are curly braces and backslash.  For example:
</p>
<div class="example">
<pre class="example">@<var>macname</var> {\\\{\}\,}
</pre></div>

<p>will pass the (almost certainly error-producing) argument
&lsquo;<samp>\{},</samp>&rsquo; to <var>macname</var>.
</p>
<p>Unfortunately, this has not been reliably implemented in TeX.  When
macros are used in the argument to other commands, for example, errors
or incorrect output (the &lsquo;<samp>\</samp>&rsquo; &ldquo;escape&rdquo; being included literally)
are likely to result.
</p>
<p>If a macro is defined to take exactly one argument, it can (but need
not) be invoked without any braces; then the entire rest of the line
after the macro name is used as the argument.  (Braces around the
argument(s) are required in all other cases, i.e., if the macro takes
either zero or more than one argument.)  For example:
</p>
<div class="example">
<pre class="example">@macro bar {p}
Twice: \p\ &amp; \p\.
@end macro
@bar aah
</pre></div>

<p>produces:
</p>
<div class="display">
<pre class="display">Twice: aah &amp; aah.
</pre></div>

<p>Likewise, if a macro is defined to take exactly one argument, and is
invoked with braces, the braced text is passed as the argument, also
regardless of commas.  For example:
</p>
<div class="example">
<pre class="example">@macro bar {p}
Twice: \p\ &amp; \p\.
@end macro
@bar{a,b}
</pre></div>

<p>produces:
</p>
<div class="display">
<pre class="display">Twice: a,b &amp; a,b.
</pre></div>

<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>


<hr>
<div class="header">
<p>
Next: <a href="Macro-Details.html#Macro-Details" accesskey="n" rel="next">Macro Details</a>, Previous: <a href="Defining-Macros.html#Defining-Macros" accesskey="p" rel="previous">Defining 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 / Invoking-Macros.html
