<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for Org version 9.3.

Copyright (C) 2004-2019  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."
 -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Macro Replacement (The Org Manual)</title>

<meta name="description" content="Macro Replacement (The Org Manual)">
<meta name="keywords" content="Macro Replacement (The Org Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Main-Index.html#Main-Index" rel="index" title="Main Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Exporting.html#Exporting" rel="up" title="Exporting">
<link href="Comment-Lines.html#Comment-Lines" rel="next" title="Comment Lines">
<link href="Include-Files.html#Include-Files" rel="prev" title="Include Files">
<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="Macro-Replacement"></a>
<div class="header">
<p>
Next: <a href="Comment-Lines.html#Comment-Lines" accesskey="n" rel="next">Comment Lines</a>, Previous: <a href="Include-Files.html#Include-Files" accesskey="p" rel="prev">Include Files</a>, Up: <a href="Exporting.html#Exporting" accesskey="u" rel="up">Exporting</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Main-Index.html#Main-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Macro-Replacement-1"></a>
<h3 class="section">13.5 Macro Replacement</h3>

<a name="index-macro-replacement_002c-during-export"></a>
<a name="index-MACRO_002c-keyword"></a>

<a name="index-org_002dexport_002dglobal_002dmacros"></a>
<p>Macros replace text snippets during export.  Macros are defined
globally in <code>org-export-global-macros</code>, or document-wise with the
following syntax:
</p>
<div class="example">
<pre class="example">#+MACRO: name   replacement text; $1, $2 are arguments
</pre></div>


<p>which can be referenced using &lsquo;<samp>{{{name(arg1, arg2)}}}</samp>&rsquo;<a name="DOCF125" href="#FOOT125"><sup>125</sup></a>.  For
example
</p>
<div class="example">
<pre class="example">#+MACRO: poem Rose is $1, violet's $2. Life's ordered: Org assists you.
{{{poem(red,blue)}}}
</pre></div>

<p>becomes
</p>
<div class="example">
<pre class="example">Rose is red, violet's blue. Life's ordered: Org assists you.
</pre></div>


<p>As a special case, Org parses any replacement text starting with
&lsquo;<samp>(eval</samp>&rsquo; as an Emacs Lisp expression and evaluates it accordingly.
Within such templates, arguments become strings.  Thus, the following
macro
</p>
<div class="example">
<pre class="example">#+MACRO: gnustamp (eval (concat &quot;GNU/&quot; (capitalize $1)))
</pre></div>


<p>turns &lsquo;<samp>{{{gnustamp(linux)}}}</samp>&rsquo; into &lsquo;<samp>GNU/Linux</samp>&rsquo; during export.
</p>
<p>Org recognizes macro references in following Org markup areas:
paragraphs, headlines, verse blocks, tables cells and lists.  Org also
recognizes macro references in keywords, such as &lsquo;<samp>CAPTION</samp>&rsquo;, &lsquo;<samp>TITLE</samp>&rsquo;,
&lsquo;<samp>AUTHOR</samp>&rsquo;, &lsquo;<samp>DATE</samp>&rsquo;, and for some back-end specific export options.
</p>
<p>Org comes with following pre-defined macros:
</p>
<dl compact="compact">
<dt>&lsquo;<samp>{{{keyword(NAME)}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{title}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{author}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{email}}}</samp>&rsquo;</dt>
<dd><a name="index-keyword_002c-macro"></a>
<a name="index-title_002c-macro"></a>
<a name="index-author_002c-macro"></a>
<a name="index-email_002c-macro"></a>
<p>The &lsquo;<samp>keyword</samp>&rsquo; macro collects all values from <var>NAME</var>
keywords throughout the buffer, separated with white space.
&lsquo;<samp>title</samp>&rsquo;, &lsquo;<samp>author</samp>&rsquo; and &lsquo;<samp>email</samp>&rsquo; macros are shortcuts for,
respectively, &lsquo;<samp>{{{keyword(TITLE)}}}</samp>&rsquo;, &lsquo;<samp>{{{keyword(AUTHOR)}}}</samp>&rsquo; and
&lsquo;<samp>{{{keyword(EMAIL)}}}</samp>&rsquo;.
</p>
</dd>
<dt>&lsquo;<samp>{{{date}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{date(FORMAT)}}}</samp>&rsquo;</dt>
<dd><a name="index-date_002c-macro"></a>
<p>This macro refers to the &lsquo;<samp>DATE</samp>&rsquo; keyword.  <var>FORMAT</var> is an
optional argument to the &lsquo;<samp>date</samp>&rsquo; macro that is used only if &lsquo;<samp>DATE</samp>&rsquo; is
a single timestamp.  <var>FORMAT</var> should be a format string
understood by <code>format-time-string</code>.
</p>
</dd>
<dt>&lsquo;<samp>{{{time(FORMAT)}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{modification-time(FORMAT, VC)}}}</samp>&rsquo;</dt>
<dd><a name="index-time_002c-macro"></a>
<a name="index-modification_002dtime_002c-macro"></a>
<p>These macros refer to the document&rsquo;s date and time of export and
date and time of modification.  <var>FORMAT</var> is a string
understood by <code>format-time-string</code>.  If the second argument to the
<code>modification-time</code> macro is non-<code>nil</code>, Org uses &lsquo;<samp>vc.el</samp>&rsquo; to retrieve
the document&rsquo;s modification time from the version control system.
Otherwise Org reads the file attributes.
</p>
</dd>
<dt>&lsquo;<samp>{{{input-file}}}</samp>&rsquo;</dt>
<dd><a name="index-input_002dfile_002c-macro"></a>
<p>This macro refers to the filename of the exported file.
</p>
</dd>
<dt>&lsquo;<samp>{{{property(PROPERTY-NAME)}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{property(PROPERTY-NAME, SEARCH OPTION)}}}</samp>&rsquo;</dt>
<dd><a name="index-property_002c-macro"></a>
<p>This macro returns the value of property <var>PROPERTY-NAME</var> in
the current entry.  If <var>SEARCH-OPTION</var> (see <a href="Search-Options.html#Search-Options">Search Options</a>) refers to a remote entry, use it instead.
</p>
</dd>
<dt>&lsquo;<samp>{{{n}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{n(NAME)}}}</samp>&rsquo;</dt>
<dt>&lsquo;<samp>{{{n(NAME, ACTION)}}}</samp>&rsquo;</dt>
<dd><a name="index-n_002c-macro"></a>
<a name="index-counter_002c-macro"></a>
<p>This macro implements custom counters by returning the number of
times the macro has been expanded so far while exporting the buffer.
You can create more than one counter using different <var>NAME</var>
values.  If <var>ACTION</var> is &lsquo;<samp>-</samp>&rsquo;, previous value of the counter
is held, i.e., the specified counter is not incremented.  If the
value is a number, the specified counter is set to that value.  If
it is any other non-empty string, the specified counter is reset
to 1.  You may leave <var>NAME</var> empty to reset the default
counter.
</p></dd>
</dl>

<a name="index-results_002c-macro"></a>
<p>Moreover, inline source blocks (see <a href="Structure-of-Code-Blocks.html#Structure-of-Code-Blocks">Structure of Code Blocks</a>) use the
special &lsquo;<samp>results</samp>&rsquo; macro to mark their output.  As such, you are
advised against re-defining it, unless you know what you are doing.
</p>
<a name="index-org_002dhide_002dmacro_002dmarkers"></a>
<p>The surrounding brackets can be made invisible by setting
<code>org-hide-macro-markers</code> to a non-<code>nil</code> value.
</p>
<p>Org expands macros at the very beginning of the export process.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT125" href="#DOCF125">(125)</a></h3>
<p>Since commas separate the arguments, commas within arguments
have to be escaped with the backslash character.  So only those
backslash characters before a comma need escaping with another
backslash character.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Comment-Lines.html#Comment-Lines" accesskey="n" rel="next">Comment Lines</a>, Previous: <a href="Include-Files.html#Include-Files" accesskey="p" rel="prev">Include Files</a>, Up: <a href="Exporting.html#Exporting" accesskey="u" rel="up">Exporting</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Main-Index.html#Main-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
