/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 6.5, 25 August 2017),
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, 2014, 2015, 2016 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 6.4.90, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Invoking Macros (GNU Texinfo 6.5)</title>

<meta name="description" content="Invoking Macros (GNU Texinfo 6.5)">
<meta name="keywords" content="Invoking Macros (GNU Texinfo 6.5)">
<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="prev" title="Defining Macros">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<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="prev">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">17.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 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-Backslash_002c-in-macro-arguments"></a>
<a name="index-Braces_002c-in-macro-arguments"></a>
<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 &lsquo;<samp>\bleh</samp>&rsquo; to <var>macname</var>.
</p>
<p><code>makeinfo</code> also recognizes &lsquo;<samp>\{</samp>&rsquo; and &lsquo;<samp>\}</samp>&rsquo; 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\ &amp; \p\.
@end macro
@bar aah
</pre></div>

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

<p>In these arguments, there is no escaping of special characters, so each
&lsquo;<samp>\</samp>&rsquo; 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>


<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="prev">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 6.5.0-1 / usr / share / doc / texinfo / html / Invoking-Macros.html
