diff options
Diffstat (limited to 'doc/groff.html.node/Calling-Macros.html')
| -rw-r--r-- | doc/groff.html.node/Calling-Macros.html | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/groff.html.node/Calling-Macros.html b/doc/groff.html.node/Calling-Macros.html new file mode 100644 index 0000000..1e8d81a --- /dev/null +++ b/doc/groff.html.node/Calling-Macros.html @@ -0,0 +1,164 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<!-- This manual documents GNU troff version 1.23.0. + +Copyright © 1994-2023 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, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled "GNU Free +Documentation License". --> +<title>Calling Macros (The GNU Troff Manual)</title> + +<meta name="description" content="Calling Macros (The GNU Troff Manual)"> +<meta name="keywords" content="Calling Macros (The GNU Troff Manual)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="Request-Index.html" rel="index" title="Request Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Formatter-Instructions.html" rel="up" title="Formatter Instructions"> +<link href="Using-Escape-Sequences.html" rel="next" title="Using Escape Sequences"> +<link href="Invoking-Requests.html" rel="prev" title="Invoking Requests"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +kbd.key {font-style: normal} +--> +</style> + + +</head> + +<body lang="en"> +<div class="subsection-level-extent" id="Calling-Macros"> +<div class="nav-panel"> +<p> +Next: <a href="Using-Escape-Sequences.html" accesskey="n" rel="next">Using Escape Sequences</a>, Previous: <a href="Invoking-Requests.html" accesskey="p" rel="prev">Invoking Requests</a>, Up: <a href="Formatter-Instructions.html" accesskey="u" rel="up">Formatter Instructions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<h4 class="subsection" id="Calling-Macros-1">5.6.3 Calling Macros</h4> +<a class="index-entry-id" id="index-calling-macros"></a> +<a class="index-entry-id" id="index-macro-arguments"></a> +<a class="index-entry-id" id="index-arguments-to-macros"></a> + +<p>If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category +‘<samp class="samp">mac</samp>’ is emitted. Calling an undefined macro <em class="emph">does</em> end a +macro definition naming it as its end macro (see <a class="pxref" href="Writing-Macros.html">Writing Macros</a>). +</p> +<a class="index-entry-id" id="index-spaces_002c-in-a-macro-argument"></a> +<p>To embed spaces <em class="emph">within</em> a macro argument, enclose the argument in +neutral double quotes <code class="code">"</code>. Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. +</p> +<p>Consider calls to a hypothetical section heading macro ‘<samp class="samp">uh</samp>’. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.uh The Mouse Problem +.uh "The Mouse Problem" +.uh The\~Mouse\~Problem +.uh The\ Mouse\ Problem +</pre></div></div> + +<a class="index-entry-id" id="index-_005c_007e_002c-difference-from-_005cSP"></a> +<a class="index-entry-id" id="index-_005cSP_002c-difference-from-_005c_007e"></a> +<p>The first line calls <code class="code">uh</code> with three arguments: ‘<samp class="samp">The</samp>’, +‘<samp class="samp">Mouse</samp>’, and ‘<samp class="samp">Problem</samp>’. The remainder call the <code class="code">uh</code> +macro with one argument, ‘<samp class="samp">The Mouse Problem</samp>’. The last solution, +using escaped spaces, can be found in documents prepared for +<abbr class="acronym">AT&T</abbr> <code class="code">troff</code>. It can cause surprise when text is +adjusted, because <code class="code">\<kbd class="key">SP</kbd></code> inserts a <em class="emph">fixed-width</em>, +non-breaking space. GNU <code class="code">troff</code>’s <code class="code">\~</code> escape sequence +inserts an adjustable, non-breaking space.<a class="footnote" id="DOCF44" href="groff.html_fot.html#FOOT44"><sup>44</sup></a> +</p> +<a class="index-entry-id" id="index-_0022_002c-embedding-in-a-macro-argument"></a> +<a class="index-entry-id" id="index-double-quote_002c-embedding-in-a-macro-argument"></a> +<a class="index-entry-id" id="index-_005c_002c-embedding-in-a-macro-argument"></a> +<a class="index-entry-id" id="index-backslash_002c-embedding-in-a-macro-argument"></a> +<p>The foregoing raises the question of how to embed neutral double quotes +or backslashes in macro arguments when <em class="emph">those</em> characters are +desired as literals. In GNU <code class="code">troff</code>, the special character escape +sequence <code class="code">\[rs]</code> produces a backslash and <code class="code">\[dq]</code> a neutral +double quote. +</p> +<p>In GNU <code class="code">troff</code>’s <abbr class="acronym">AT&T</abbr> compatibility mode, these +characters remain available as <code class="code">\(rs</code> and <code class="code">\(dq</code>, +respectively. <abbr class="acronym">AT&T</abbr> <code class="code">troff</code> did not consistently define +these special characters, +but its descendants can be made to support them. See <a class="xref" href="Device-and-Font-Description-Files.html">Device and Font Description Files</a>. +</p> +<p>If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. See <a class="xref" href="Using-Escape-Sequences.html">Using Escape Sequences</a>. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. See <a class="xref" href="Copy-Mode.html">Copy Mode</a>. +</p> +<p>For the (neutral) double quote, you have recourse to an obscure +syntactical feature of <abbr class="acronym">AT&T</abbr> <code class="code">troff</code>. Because a double +quote can begin a macro argument, the formatter keeps track of whether +the current argument was started thus, and doesn’t require a space after +the double quote that ends it.<a class="footnote" id="DOCF45" href="groff.html_fot.html#FOOT45"><sup>45</sup></a> In +the argument list to a macro, a double quote that <em class="emph">isn’t</em> preceded +by a space <em class="emph">doesn’t</em> start a macro argument. If not preceded by a +double quote that began an argument, this double quote becomes part of +the argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.de eq +. tm arg1:\\$1 arg2:\\$2 arg3:\\$3 +. tm arg4:\\$4 arg5:\\$5 arg6:\\$6 +.. \" 4 backslashes on the next line +.eq a" "b c" "de"f\\\\g" h""i "j""k" + error→ arg1:a" arg2:b c arg3:de + error→ arg4:f\g" arg5:h""i arg6:j"k +</pre></div></div> + +<p>Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don’t survive repeated argument +expansion in <abbr class="acronym">AT&T</abbr> <code class="code">troff</code> or GNU <code class="code">troff</code>’s +compatibility mode. This can frustrate efforts to pass such arguments +intact through multiple macro calls. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.cp 1 +.de eq +. tm arg1:\\$1 arg2:\\$2 arg3:\\$3 +. tm arg4:\\$4 arg5:\\$5 arg6:\\$6 +.. +.de xe +. eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 +.. \" 8 backslashes on the next line +.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k" + error→ arg1:a" arg2:b arg3:c + error→ arg4:de arg5:f\g" arg6:h""i +</pre></div></div> + +<a class="index-entry-id" id="index-input-level"></a> +<a class="index-entry-id" id="index-level_002c-input"></a> +<a class="index-entry-id" id="index-interpolation-depth"></a> +<a class="index-entry-id" id="index-depth_002c-interpolation"></a> +<p>Outside of compatibility mode, GNU <code class="code">troff</code> doesn’t exhibit this +problem because it tracks the nesting depth of interpolations. +See <a class="xref" href="Implementation-Differences.html">Implementation Differences</a>. +</p> + +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="Using-Escape-Sequences.html">Using Escape Sequences</a>, Previous: <a href="Invoking-Requests.html">Invoking Requests</a>, Up: <a href="Formatter-Instructions.html">Formatter Instructions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |