[master] clarify size_spec in ARM

3503.	[doc]		Clarify size_spec syntax. [RT #32449]

diff --git a/CHANGES b/CHANGES
index 1cd654e32073b30ce961def1b3d1bd69689057c5..61e37731e92480b7acba6b8996a5b91fe2d732f3 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,5 @@
+3503.  [doc]           Clarify size_spec syntax. [RT #32449]
+
 3502.  [func]          zone-statistics: "no" is now a synonym for "none",
                        instead of "terse". [RT #29165]
 

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index e90305a9cdc5d4438af992727a95cfeae9ee5b7e..7a8e3da7a7464408be3f16ef6ebd6fd44ce55eb7 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -3406,31 +3406,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>