[v9_6] clarify size_spec in ARM

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

diff --git a/CHANGES b/CHANGES
index feb5d0ea82d4034571462bb9b61673f86e11fdec..c91d2b1fbb34431804126bbc10b0055204a9fcd0 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,5 @@
+3503.  [doc]           Clarify size_spec syntax. [RT #32449]
+
 3499.  [doc]           Corrected ARM documentation of built-in zones.
                        [RT #32694]
 

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