clarify descriptions of comment-related options in dig usage and man page

diff --git a/bin/dig/dig.c b/bin/dig/dig.c
index 984ec1eaf87423a4446cab42974c42fced1a8527..1c425fddf66396dd2bea55253086899a56c28ae3 100644 (file)
--- a/bin/dig/dig.c
+++ b/bin/dig/dig.c
@@ -173,11 +173,13 @@ help(void) {
 "                 +bufsize=###        (Set EDNS0 Max UDP packet size)\n"
 "                 +[no]cdflag         (Set checking disabled flag in query)\n"
 "                 +[no]class          (Control display of class in records)\n"
-"                 +[no]cmd            (Control display of command line)\n"
-"                 +[no]comments       (Control display of comment lines)\n"
+"                 +[no]cmd            (Control display of command line -\n"
+"                                      global option)\n"
+"                 +[no]comments       (Control display of packet header\n"
+"                                      and section name comments)\n"
 "                 +[no]cookie         (Add a COOKIE option to the request)\n"
-"                 +[no]crypto         (Control display of cryptographic "
-                                      "fields in records)\n"
+"                 +[no]crypto         (Control display of cryptographic\n"
+"                                      fields in records)\n"
 "                 +[no]defname        (Use search list (+[no]search))\n"
 "                 +[no]dnssec         (Request DNSSEC records)\n"
 "                 +domain=###         (Set default domainname)\n"
@@ -194,11 +196,13 @@ help(void) {
 "                 +[no]identify       (ID responders in short answers)\n"
 #ifdef HAVE_LIBIDN2
 "                 +[no]idnin          (Parse IDN names [default=on on tty])\n"
-"                 +[no]idnout         (Convert IDN response [default=on on tty])\n"
+"                 +[no]idnout         (Convert IDN response "
+                                       "[default=on on tty])\n"
 #endif
 "                 +[no]ignore         (Don't revert to TCP for TC responses.)\n"
 "                 +[no]keepalive      (Request EDNS TCP keepalive)\n"
-"                 +[no]keepopen       (Keep the TCP socket open between queries)\n"
+"                 +[no]keepopen       (Keep the TCP socket open between "
+                                       "queries)\n"
 "                 +[no]mapped         (Allow mapped IPv4 over IPv6)\n"
 "                 +[no]multiline      (Print records in an expanded format)\n"
 "                 +ndots=###          (Set search NDOTS value)\n"
@@ -217,7 +221,7 @@ help(void) {
                                        "comments)\n"
 "                 +[no]search         (Set whether to use searchlist)\n"
 "                 +[no]short          (Display nothing except short\n"
-"                                      form of answer)\n"
+"                                      form of answers - global option)\n"
 "                 +[no]showsearch     (Search with intermediate results)\n"
 "                 +[no]split=##       (Split hex/base64 fields into chunks)\n"
 "                 +[no]stats          (Control display of statistics)\n"
@@ -225,11 +229,13 @@ help(void) {
 "                 +[no]tcflag         (Set TC flag in query (+[no]tcflag))\n"
 "                 +[no]tcp            (TCP mode (+[no]vc))\n"
 "                 +timeout=###        (Set query timeout) [5]\n"
-"                 +[no]trace          (Trace delegation down from root [+dnssec])\n"
+"                 +[no]trace          (Trace delegation down from root "
+                                       "[+dnssec])\n"
 "                 +tries=###          (Set number of UDP attempts) [3]\n"
 "                 +[no]ttlid          (Control display of ttls in records)\n"
 "                 +[no]ttlunits       (Display TTLs in human-readable units)\n"
-"                 +[no]unknownformat  (Print RDATA in RFC 3597 \"unknown\" format)\n"
+"                 +[no]unknownformat  (Print RDATA in RFC 3597 \"unknown\" "
+                                       "format)\n"
 "                 +[no]vc             (TCP mode (+[no]tcp))\n"
 "                 +[no]zflag          (Set Z flag in query)\n"
 "        global d-opts and servers (before host name) affect all queries.\n"

diff --git a/bin/dig/dig.docbook b/bin/dig/dig.docbook
index 0e5e374a0dc816fa374b6ff53a3801a41645c603..8d16e76a561c7a01e1035e34fbe98554e09348f3 100644 (file)
--- a/bin/dig/dig.docbook
+++ b/bin/dig/dig.docbook
@@ -593,9 +593,11 @@
          <listitem>
            <para>
              Toggles the printing of the initial comment in the
-             output identifying the version of <command>dig</command>
-             and the query options that have been applied.  This
-             comment is printed by default.
+             output, identifying the version of <command>dig</command>
+             and the query options that have been applied.  This option
+             always has global effect; it cannot be set globally
+             and then overridden on a per-lookup basis.  The default
+             is to print this comment.
            </para>
          </listitem>
        </varlistentry>
@@ -604,8 +606,18 @@
          <term><option>+[no]comments</option></term>
          <listitem>
            <para>
-             Toggle the display of comment lines in the output.
-             The default is to print comments.
+             Toggles the display of some comment lines in the output,
+             containing information about the packet header and
+             OPT pseudosection, and the names of the response
+             section.  The default is to print these comments.
+           </para>
+           <para>
+             Other types of comments in the output are not affected by
+             this option, but can be controlled using other command
+             line switches. These include <command>+[no]cmd</command>,
+             <command>+[no]question</command>,
+             <command>+[no]stats</command>, and
+             <command>+[no]rrcomments</command>.
            </para>
          </listitem>
        </varlistentry>
@@ -965,8 +977,8 @@
          <term><option>+[no]qr</option></term>
          <listitem>
            <para>
-             Print [do not print] the query as it is sent.  By
-             default, the query is not printed.
+             Toggles the display of the query message as it is sent.
+             By default, the query is not printed.
            </para>
          </listitem>
        </varlistentry>
@@ -975,7 +987,7 @@
          <term><option>+[no]question</option></term>
          <listitem>
            <para>
-             Print [do not print] the question section of a query
+             Toggles the display of the question section of a query
              when an answer is returned.  The default is to print
              the question section as a comment.
            </para>
@@ -1066,7 +1078,9 @@
          <listitem>
            <para>
              Provide a terse answer.  The default is to print the
-             answer in a verbose form.
+             answer in a verbose form.  This option always has global
+             effect; it cannot be set globally and then overridden on
+             a per-lookup basis.
            </para>
          </listitem>
        </varlistentry>
@@ -1111,10 +1125,9 @@
          <term><option>+[no]stats</option></term>
          <listitem>
            <para>
-             This query option toggles the printing of statistics:
-             when the query was made, the size of the reply and
-             so on.  The default behavior is to print the query
-             statistics.
+             Toggles the printing of statistics: when the query was made,
+             the size of the reply and so on.  The default behavior is to
+             print the query statistics as a comment after each lookup.
            </para>
          </listitem>
        </varlistentry>