[v9_9] clarify size_spec in ARM

3503.	[doc]		Clarify size_spec syntax. [RT #32449]
(cherry picked from commit de1223830f23c2fcd343e40d0940aa591fc363b6)

diff --git a/CHANGES b/CHANGES
index 3df946f4b7b6ae81d8ed6cdc5dcb0ad0c7802fc7..bebe0cd913605fbd5948fd49996b47c1df666923 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,5 @@
+3503.  [doc]           Clarify size_spec syntax. [RT #32449]
+
 3501.  [func]          zone-statistics now takes three options: full,
                        terse, and none. "yes" and "no" are retained as
                        synonyms for full and terse, respectively. [RT #29165]

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index c54ec0b1e4ea62a343a6dcc0547e6ae948a30e54..391c18eb99ffbd540f6c62f1eaf69230dc833f8c 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -3384,31 +3384,45 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
               </entry>
               <entry colname="2">
                 <para>
-                  A number, the word <userinput>unlimited</userinput>,
-                  or the word <userinput>default</userinput>.
+                  A 64-bit unsigned integer, or the keywords
+                  <userinput>unlimited</userinput> or
+                  <userinput>default</userinput>.
                 </para>
-               <para>
-                  An <varname>unlimited</varname> <varname>size_spec</varname> requests unlimited
-                  use, or the maximum available amount. A <varname>default size_spec</varname> uses
-                  the limit that was in force when the server was started.
+                <para>
+                  Integers may take values
+                  0 &lt;= value &lt;= 18446744073709551615, though
+                  certain parameters may use a more limited range
+                  within these extremes.  In most cases, setting a
+                  value to 0 does not literally mean zero; it means
+                  "undefined" or "as big as psosible", depending on
+                  the context. See the expalantions of particular
+                  parameters that use <varname>size_spec</varname>
+                  for details on how they interpret its use. 
                 </para>
                 <para>
-                  A <varname>number</varname> can optionally be
-                 followed by a scaling factor:
+                  Numeric values can optionally be followed by a
+                  scaling factor:
                  <userinput>K</userinput> or <userinput>k</userinput>
                  for kilobytes,
                  <userinput>M</userinput> or <userinput>m</userinput>
                  for megabytes, and
-                 <userinput>G</userinput> or <userinput>g</userinput> for gigabytes,
-                  which scale by 1024, 1024*1024, and 1024*1024*1024
-                  respectively.
+                  <userinput>G</userinput> or <userinput>g</userinput>
+                  for gigabytes, which scale by 1024, 1024*1024, and
+                  1024*1024*1024 respectively.
                 </para>
-                <para>
-                  The value must be representable as a 64-bit unsigned integer
-                  (0 to 18446744073709551615, inclusive).
-                  Using <varname>unlimited</varname> is the best
-                  way
-                  to safely set a really large number.
+               <para>
+                  <varname>unlimited</varname> generally means
+                  "as big as possible", though in certain contexts,
+                  (including <option>max-cache-size</option>), it may
+                  mean the largest possible 32-bit unsigned integer
+                  (0xffffffff); this distinction can be important when
+                  dealing with larger quantities. 
+                  <varname>unlimited</varname> is usually the best way
+                  to safely set a very large number.
+                </para>
+               <para>
+                  <varname>default</varname> 
+                  uses the limit that was in force when the server was started.
                 </para>
               </entry>
             </row>