diff options
Diffstat (limited to 'doc/groff.html.node/Using-Escape-Sequences.html')
| -rw-r--r-- | doc/groff.html.node/Using-Escape-Sequences.html | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/doc/groff.html.node/Using-Escape-Sequences.html b/doc/groff.html.node/Using-Escape-Sequences.html new file mode 100644 index 0000000..9eabad1 --- /dev/null +++ b/doc/groff.html.node/Using-Escape-Sequences.html @@ -0,0 +1,206 @@ +<!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>Using Escape Sequences (The GNU Troff Manual)</title> + +<meta name="description" content="Using Escape Sequences (The GNU Troff Manual)"> +<meta name="keywords" content="Using Escape Sequences (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="Delimiters.html" rel="next" title="Delimiters"> +<link href="Calling-Macros.html" rel="prev" title="Calling Macros"> +<style type="text/css"> +<!-- +a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em} +div.example {margin-left: 3.2em} +span.r {font-family: initial; font-weight: normal; font-style: normal} +span:hover a.copiable-link {visibility: visible} +strong.def-name {font-family: monospace; font-weight: bold; font-size: larger} +--> +</style> + + +</head> + +<body lang="en"> +<div class="subsection-level-extent" id="Using-Escape-Sequences"> +<div class="nav-panel"> +<p> +Next: <a href="Delimiters.html" accesskey="n" rel="next">Delimiters</a>, Previous: <a href="Calling-Macros.html" accesskey="p" rel="prev">Calling Macros</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="Using-Escape-Sequences-1">5.6.4 Using Escape Sequences</h4> +<a class="index-entry-id" id="index-using-escape-sequences"></a> +<a class="index-entry-id" id="index-escape-sequences"></a> + +<p>Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. +<a class="index-entry-id" id="index-_005c"></a> +An escape sequence is introduced by the escape character, a backslash +<code class="code">\</code> (but see the <code class="code">ec</code> request below). The next character +selects the escape’s function. +</p> +<p>Escape sequences vary in length. Some take an argument, and of those, +some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept <em class="emph">only</em> +an arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis ‘<samp class="samp">(</samp>’ introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets ‘<samp class="samp">[]</samp>’. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions (<code class="code">\s</code>), designate their own +termination sequence (<code class="code">\?</code>), consume input until the next newline +(<code class="code">\!</code>, <code class="code">\"</code>, <code class="code">\#</code>), or support an additional modifier +character (<code class="code">\s</code> again, and <code class="code">\n</code>). As with requests, use of +some escape sequences in source documents may interact poorly with a +macro package you use; consult its documentation to learn of “safe” +sequences or alternative facilities it provides to achieve the desired +result. +</p> +<p>If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the ‘<samp class="samp">escape</samp>’ warning category, which is not enabled +by default) and the following character is processed normally. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">$ groff -Tps -ww +.nr N 12 +.ds co white +.ds animal elephant +I have \fI\nN \*(co \*[animal]s,\f[] +said \P.\&\~Pseudo Pachyderm. + error→ warning: escape character ignored before 'P' + ⇒ I have <i class="slanted">12 white elephants,</i> said P. Pseudo Pachyderm. +</pre></div></div> + +<p>Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.ds family C\" Courier +.ds style I\" oblique +Choice a typeface \f(\*[family]\*[style]wisely. + ⇒ Choose a typeface <i class="slanted">wisely.</i> +</pre></div></div> + +<p>In the above, the syntax form ‘<samp class="samp">\f(</samp>’ accepts only two characters for +an argument; the example works because the subsequent escape sequences +are interpolated before the selection escape sequence argument is +processed, and strings <code class="code">family</code> and <code class="code">style</code> interpolate one +character each.<a class="footnote" id="DOCF46" href="groff.html_fot.html#FOOT46"><sup>46</sup></a> +</p> +<p>The escape character is nearly always interpreted when encountered; it +is therefore desirable to have a way to interpolate it, disable it, or +change it. +</p> +<a class="index-entry-id" id="index-formatting-the-escape-character-_0028_005ce_0029"></a> +<a class="index-entry-id" id="index-escape-character_002c-formatting-_0028_005ce_0029"></a> +<dl class="first-deffn"> +<dt class="deffn" id="index-_005ce-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\e</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005ce-1'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-_005ce"></a> +<p>Interpolate the escape character. +</p></dd></dl> + +<a class="index-entry-id" id="index-formatting-a-backslash-glyph-_0028_005c_005brs_005d_0029"></a> +<a class="index-entry-id" id="index-backslash-glyph_002c-formatting-_0028_005c_005brs_005d_0029"></a> +<p>The <code class="code">\[rs]</code> special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences <code class="code">\\</code> +and <code class="code">\E</code> defer interpretation of escape sequences. See <a class="xref" href="Copy-Mode.html">Copy Mode</a>. +</p> +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eeo"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.eo</code></strong><a class="copiable-link" href='#index-_002eeo'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-eo"></a> +<a class="index-entry-id" id="index-disabling-_005c-_0028eo_0029"></a> +<a class="index-entry-id" id="index-_005c_002c-disabling-_0028eo_0029"></a> +<p>Disable the escape mechanism except in copy mode. Once this request is +invoked, no input character is recognized as starting an escape +sequence in interpretation mode. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eec"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ec</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">o</i></span>]</var><a class="copiable-link" href='#index-_002eec'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ec"></a> +<a class="index-entry-id" id="index-escape-character_002c-changing-_0028ec_0029"></a> +<a class="index-entry-id" id="index-character_002c-escape_002c-changing-_0028ec_0029"></a> +<p>Recognize the ordinary character <var class="var">o</var> as the escape character. +If <var class="var">o</var> is absent or invalid, the default escape character +‘<samp class="samp">\</samp>’ is selected. +</p></dd></dl> + +<p>Switching escape sequence interpretation off to define a macro and back +on afterward can obviate the need to double the escape character within +the definition. See <a class="xref" href="Writing-Macros.html">Writing Macros</a>. This technique is not available +if your macro needs to interpolate values at the time it is +<em class="emph">defined</em>—but many do not. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.\" simplified `BR` macro from the man(7) macro package +.eo +.de BR +. ds result \& +. while (\n[.$] >= 2) \{\ +. as result \fB\$1\fR\$2\" +. shift 2 +. \} +. if \n[.$] .as result \fB\$1\" +\*[result] +. rm result +. ft R +.. +.ec +</pre></div></div> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eecs"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ecs</code></strong><a class="copiable-link" href='#index-_002eecs'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ecs"></a> +</dd><dt class="deffnx def-cmd-deffn" id="index-_002eecr"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ecr</code></strong><a class="copiable-link" href='#index-_002eecr'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ecr"></a> +<p>The <code class="code">ecs</code> request stores the escape character for recall with +<code class="code">ecr</code>. <code class="code">ecr</code> sets the escape character to ‘<samp class="samp">\</samp>’ if none +has been saved. +</p> +<p>Use these requests together to temporarily change the escape character. +</p></dd></dl> + +<p>Using a different escape character, or disabling it, when calling macros +not under your control will likely cause errors, since GNU <code class="code">troff</code> +has no mechanism to “intern” macros—that is, to convert a macro +definition into a form independent of its +representation.<a class="footnote" id="DOCF47" href="groff.html_fot.html#FOOT47"><sup>47</sup></a> When a +macro is called, its contents are interpreted literally. +</p> + +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="Delimiters.html">Delimiters</a>, Previous: <a href="Calling-Macros.html">Calling Macros</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> |