doc/groff.html.node/Comments.html

   1 <!DOCTYPE html>
   2 <html>
   3 <!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <!-- This manual documents GNU troff version 1.23.0.
   7
   8 Copyright © 1994-2023 Free Software Foundation, Inc.
   9
  10 Permission is granted to copy, distribute and/or modify this document
  11 under the terms of the GNU Free Documentation License, Version 1.3 or
  12 any later version published by the Free Software Foundation; with no
  13 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  14 copy of the license is included in the section entitled "GNU Free
  15 Documentation License". -->
  16 <title>Comments (The GNU Troff Manual)</title>
  17
  18 <meta name="description" content="Comments (The GNU Troff Manual)">
  19 <meta name="keywords" content="Comments (The GNU Troff Manual)">
  20 <meta name="resource-type" content="document">
  21 <meta name="distribution" content="global">
  22 <meta name="Generator" content="makeinfo">
  23 <meta name="viewport" content="width=device-width,initial-scale=1">
  24
  25 <link href="index.html" rel="start" title="Top">
  26 <link href="Request-Index.html" rel="index" title="Request Index">
  27 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  28 <link href="GNU-troff-Reference.html" rel="up" title="GNU troff Reference">
  29 <link href="Registers.html" rel="next" title="Registers">
  30 <link href="Formatter-Instructions.html" rel="prev" title="Formatter Instructions">
  31 <style type="text/css">
  32 <!--
  33 a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
  34 div.example {margin-left: 3.2em}
  35 span.r {font-family: initial; font-weight: normal; font-style: normal}
  36 span:hover a.copiable-link {visibility: visible}
  37 strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
  38 -->
  39 </style>
  40
  41
  42 </head>
  43
  44 <body lang="en">
  45 <div class="section-level-extent" id="Comments">
  46 <div class="nav-panel">
  47 <p>
  48 Next: <a href="Registers.html" accesskey="n" rel="next">Registers</a>, Previous: <a href="Formatter-Instructions.html" accesskey="p" rel="prev">Formatter Instructions</a>, Up: <a href="GNU-troff-Reference.html" accesskey="u" rel="up">GNU <code class="code">troff</code> Reference</a> &nbsp; [<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>
  49 </div>
  50 <hr>
  51 <h3 class="section" id="Comments-1">5.7 Comments</h3>
  52 <a class="index-entry-id" id="index-comments"></a>
  53
  54 <p>One of the most common forms of escape sequence is the
  55 comment.<a class="footnote" id="DOCF48" href="groff.html_fot.html#FOOT48"><sup>48</sup></a>
  56 </p>
  57 <dl class="first-deffn">
  58 <dt class="deffn" id="index-_005c_0022-1"><span class="category-def">Escape&nbsp;sequence: </span><span><strong class="def-name"><code class="t">\&quot;</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0022-1'> &para;</a></span></dt>
  59 <dd><a class="index-entry-id" id="index-_005c_0022"></a>
  60 <p>Start a comment.  Everything up to the next newline is ignored.
  61 </p>
  62 <p>This may sound simple, but it can be tricky to keep the comments from
  63 interfering with the appearance of the output.
  64 <a class="index-entry-id" id="index-ds_002c-ds1-requests_002c-and-comments"></a>
  65 <a class="index-entry-id" id="index-as_002c-as1-requests_002c-and-comments"></a>
  66 If the escape sequence is to the right of some text or a request, that
  67 portion of the line is ignored, but spaces preceding it are processed
  68 normally by GNU <code class="code">troff</code>.  This affects only the <code class="code">ds</code> and
  69 <code class="code">as</code> requests and their variants.
  70 </p>
  71 <a class="index-entry-id" id="index-tabs_002c-before-comments"></a>
  72 <a class="index-entry-id" id="index-comments_002c-lining-up-with-tabs"></a>
  73 <p>One possibly irritating idiosyncrasy is that tabs should not be used to
  74 vertically align comments in the source document.  Tab characters are
  75 not treated as separators between a request name and its first argument,
  76 nor between arguments.
  77 </p>
  78 <a class="index-entry-id" id="index-undefined-request"></a>
  79 <a class="index-entry-id" id="index-request_002c-undefined"></a>
  80 <p>A comment on a line by itself is treated as a blank line, because after
  81 eliminating the comment, that is all that remains.
  82 </p>
  83 <div class="example">
  84 <div class="group"><pre class="example-preformatted">Test
  85 \&quot; comment
  86 Test
  87     &rArr; Test
  88     &rArr;
  89     &rArr; Test
  90 </pre></div></div>
  91
  92 <p>To avoid this, it is common to combine the empty request with the
  93 comment escape sequence as &lsquo;<samp class="samp">.\&quot;</samp>&rsquo;, causing the input line to be
  94 ignored.
  95 </p>
  96 <a class="index-entry-id" id="index-_0027_002c-as-a-comment"></a>
  97 <p>Another commenting scheme sometimes seen is three consecutive single
  98 quotes (<code class="code">'''</code>) at the beginning of a line.  This works, but GNU
  99 <code class="code">troff</code> emits a warning diagnostic (if enabled) about an undefined
 100 macro (namely &lsquo;<samp class="samp">''</samp>&rsquo;).
 101 </p></dd></dl>
 102
 103 <dl class="first-deffn">
 104 <dt class="deffn" id="index-_005c_0023-1"><span class="category-def">Escape&nbsp;sequence: </span><span><strong class="def-name"><code class="t">\#</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0023-1'> &para;</a></span></dt>
 105 <dd><a class="index-entry-id" id="index-_005c_0023"></a>
 106 <p>Start a comment; everything up to and including the next newline is
 107 ignored.  This <code class="code">groff</code> extension was introduced to avoid the
 108 problems described above.
 109 </p>
 110 <div class="example">
 111 <div class="group"><pre class="example-preformatted">Test
 112 \# comment
 113 Test
 114     &rArr; Test Test
 115 </pre></div></div>
 116 </dd></dl>
 117
 118 <dl class="first-deffn">
 119 <dt class="deffn" id="index-_002eig"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ig</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">end</i></span>]</var><a class="copiable-link" href='#index-_002eig'> &para;</a></span></dt>
 120 <dd><a class="index-entry-id" id="index-ig"></a>
 121 <p>Ignore input until, in the current conditional block (if
 122 any),<a class="footnote" id="DOCF49" href="groff.html_fot.html#FOOT49"><sup>49</sup></a> the macro <var class="var">end</var> is called
 123 at the start of a control line, or the control line &lsquo;<samp class="samp">..</samp>&rsquo; is
 124 encountered if <var class="var">end</var> is not specified.  <code class="code">ig</code> is parsed as if it
 125 were a macro definition, but its contents are discarded, not
 126 stored.<a class="footnote" id="DOCF50" href="groff.html_fot.html#FOOT50"><sup>50</sup></a>
 127 </p>
 128 <div class="example">
 129 <div class="group"><pre class="example-preformatted">hand\c
 130 .de TX
 131 fasting
 132 ..
 133 .ig TX
 134 This is part of a large block of input that has been
 135 temporarily(?) commented out.
 136 We can restore it simply by removing the .ig request and
 137 the call of its end macro.
 138 .TX
 139 </pre></div></div>
 140 <div class="example">
 141 <div class="group"><pre class="example-preformatted">    &rArr; handfasting
 142 </pre></div></div>
 143 </dd></dl>
 144
 145
 146
 147 </div>
 148 <hr>
 149 <div class="nav-panel">
 150 <p>
 151 Next: <a href="Registers.html">Registers</a>, Previous: <a href="Formatter-Instructions.html">Formatter Instructions</a>, Up: <a href="GNU-troff-Reference.html">GNU <code class="code">troff</code> Reference</a> &nbsp; [<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>
 152 </div>
 153
 154
 155
 156 </body>
 157 </html>