PATCH: 3.1.6-pre-1: document HISTSIZE/SAVEHIST caveat

[Wayne Davison <wayne@xxxxxxxxx>]

Here's a couple tweaks to the documentation that mentions the
usefulness of setting HISTSIZE larger than SAVEHIST when you use
HIST_EXPIRE_DUPS_FIRST.

..wayne..
---8<------8<------8<------8<---cut here--->8------>8------>8------>8---
Index: Doc/Zsh/options.yo
@@ -416,9 +416,13 @@
 pindex(HIST_EXPIRE_DUPS_FIRST)
 cindex(history, expiring duplicates)
 item(tt(HIST_EXPIRE_DUPS_FIRST))(
-If the internal history needs to be trimmed to add a new line,
-setting this option will cause the oldest duplicate history line to
-be lost before losing a unique line from the list.
+If the internal history needs to be trimmed to add the current command line,
+setting this option will cause the oldest history event that has a duplicate
+to be lost before losing a unique event from the list.
+You should be sure to set the value of tt(HISTSIZE) to a larger number
+than tt(SAVEHIST) in order to give you some room for the duplicated
+events, otherwise this option will behave just like
+tt(HIST_IGNORE_ALL_DUPS) once the history fills up with unique events.
 )
 pindex(HIST_IGNORE_ALL_DUPS)
 cindex(history, ignoring all duplicates)
Index: Doc/Zsh/params.yo
@@ -507,7 +507,10 @@
 )
 vindex(HISTSIZE)
 item(tt(HISTSIZE) <S>)(
-The maximum size of the history list.
+The maximum number of events stored in the internal history list.
+If you use the tt(HIST_EXPIRE_DUPS_FIRST) option, setting this value
+larger than the tt(SAVEHIST) size will give you the difference as a
+cushion for saving duplicated history events.
 )
 vindex(HOME)
 item(tt(HOME) <S>)(
---8<------8<------8<------8<---cut here--->8------>8------>8------>8---