doc: Edits to the 'afsd -volume-ttl' manpage

Make a few misc changes to the text for the new -volume-ttl option:

- Minor grammatical/typo fixes

- Emphasize a little more that the default behavior allows for vldb
  info to be cached _forever_

- Provide some info on the effects of changing this value

- Provide a suggested "typical" value, to give some clue as to what
  should be set here, so a curious user doesn't just set this to the
  first value they see (10 minutes)

Change-Id: Ib6b2871b111c392260ea80e26273201b09d4c402
Reviewed-on: https://gerrit.openafs.org/12909
Reviewed-by: Benjamin Kaduk <kaduk@mit.edu>
Tested-by: Andrew Deason <adeason@sinenomine.net>

diff --git a/doc/man-pages/pod8/afsd.pod b/doc/man-pages/pod8/afsd.pod
index 6114a7e..65a27a6 100644 (file)
--- a/doc/man-pages/pod8/afsd.pod
+++ b/doc/man-pages/pod8/afsd.pod
@@ -760,14 +760,21 @@ Specifies the maximum amount of time the Cache Manager will cache volume
 information retrieved from VL Servers.
 
 By default, the Cache Manager will cache read-only volume information as long
-as a volume callback is held for a read-only volume. The callback may be held
-as long as files in the read-only volume are being accessed.  The Cache Manager
-will cache read/write volume information as long as volume level errors are not
-returned from fileservers while accessing files within the volume.
-
-Use the B<-volume-ttl> to specify the maximum amount of time in seconds
-volume information will be cached, regardless of connectivity to the
-fileserers. The minimum valid value is 600 seconds (10 minutes).
+as a volume callback is held for that volume. The callback may be held as long
+as files in the read-only volume are being accessed, with no upper limit. For
+read/write volumes, by default the Cache Manager will cache volume information
+forever, until a fileserver returns a volume-level error in response to
+accessing files in that volume.
+
+Use the B<-volume-ttl> option to specify the maximum amount of time in seconds
+that volume information will be cached, regardless of connectivity to the
+fileservers. Lowering this value can make the Cache Manager recover more
+quickly from certain volume/fileserver errors, but will increase the load on
+the VL Servers for contacted cells.
+
+A typical value is 7200 seconds (2 hours), which is the same as the default
+callback duration for read-only volumes. The minimum valid value is 600 seconds
+(10 minutes).
 
 =back