Docs: mention byte units and maximum_object_size/cache_dir relationship

* we are having users configure rounded n MB or n GB values as KB numbers
  unnecessarily from misunderstanding the unit measures. Document which
  units Squid understands to assist simplifying these configs.

* the maximum_object_size directive has been a "toggle" default for
  cache_dir max-size for some time but the dependency of having it
  placed before cache_dir it is supposed to affect has not been
  documented. Add the documentation, and re-order the default config
  directive positions.

diff --git a/src/cf.data.pre b/src/cf.data.pre
index bde3b51bbe8a080e7efc27af4618725e864f8933..d5931c3328c972a34e84a78356d2722ffc26df8a 100644 (file)
--- a/src/cf.data.pre
+++ b/src/cf.data.pre
@@ -64,6 +64,17 @@ COMMENT_START
   from causing Squid entering an infinite loop whilst trying to load
   configuration files.
 
+  Values with byte units
+
+       Squid supports some directive parameters in bytes with a unit
+       measure. All such directives are documented with a default value
+       displaying a unit measure.
+
+       Units accepted by Squid are:
+               bytes - bytes
+               KB - Kilobyte
+               MB - Megabyte
+               GB - Gigabyte
 
   Values with spaces, quotes, and other special characters
 
@@ -3383,6 +3394,41 @@ DOC_START
        and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
 DOC_END
 
+NAME: minimum_object_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 0 KB
+DEFAULT_DOC: no limit
+LOC: Config.Store.minObjectSize
+DOC_START
+       Objects smaller than this size will NOT be saved on disk.  The
+       value is specified in bytes, and the default is 0 KB, which
+       means all responses can be stored.
+DOC_END
+
+NAME: maximum_object_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 4 MB
+LOC: Config.Store.maxObjectSize
+DOC_START
+       Set the default value for max-size parameter on any cache_dir
+       which follow.
+       
+       The value is specified in bytes, and the default is 4 MB.
+       
+       If you wish to get a high BYTES hit ratio, you should probably
+       increase this (one 32 MB object hit counts for 3200 10KB
+       hits).
+       
+       If you wish to increase hit ratio more than you want to
+       save bandwidth you should leave this low.
+       
+       NOTE: if using the LFUDA replacement policy you should increase
+       this value to maximize the byte hit rate improvement of LFUDA!
+       See cache_replacement_policy for a discussion of this policy.
+DOC_END
+
 NAME: cache_dir
 TYPE: cachedir
 DEFAULT: none
@@ -3532,9 +3578,10 @@ DOC_START
 
        max-size=n      the maximum object size in bytes this cache_dir
                        supports.
-                       The value in maximum_object_size directive, sets
-                       a default unless more specific details are available
-                       about the cache_dir (ie a small store capacity).
+                       The value in maximum_object_size directive above
+                       this cache_dir line sets a default unless more
+                       specific details are available (ie a small store
+                       capacity).
 
        Note: To make optimal use of the max-size limits you should order
        the cache_dir lines with the smallest max-size value first.
@@ -3607,40 +3654,6 @@ DOC_START
        A value of 0 indicates no limit.
 DOC_END
 
-NAME: minimum_object_size
-COMMENT: (bytes)
-TYPE: b_int64_t
-DEFAULT: 0 KB
-DEFAULT_DOC: no limit
-LOC: Config.Store.minObjectSize
-DOC_START
-       Objects smaller than this size will NOT be saved on disk.  The
-       value is specified in bytes, and the default is 0 KB, which
-       means all responses can be stored.
-DOC_END
-
-NAME: maximum_object_size
-COMMENT: (bytes)
-TYPE: b_int64_t
-DEFAULT: 4 MB
-LOC: Config.Store.maxObjectSize
-DOC_START
-       The default limit on size of objects stored to disk.
-       This size is used for cache_dir where max-size is not set.
-       The value is specified in bytes, and the default is 4 MB.
-
-       If you wish to get a high BYTES hit ratio, you should probably
-       increase this (one 32 MB object hit counts for 3200 10KB
-       hits).
-
-       If you wish to increase hit ratio more than you want to
-       save bandwidth you should leave this low.
-
-       NOTE: if using the LFUDA replacement policy you should increase
-       this value to maximize the byte hit rate improvement of LFUDA!
-       See replacement_policy below for a discussion of this policy.
-DOC_END
-
 NAME: cache_swap_low
 COMMENT: (percent, 0-100)
 TYPE: int