Add v21 release notes, minor documentation update.

ChangeLog

@@ -2,15 +2,91 @@
 # Summary of release changes, see commit history for more details:
 # https://github.com/joelthelion/autojump/commits/master/
 
+* Release v21:
+
+ - New mailing list for developer discussion and announcements:
+
+   https://groups.google.com/forum/?fromgroups%5C#!forum/autojump
+
+ - Switch to semantic versioning (http://semver.org/): major.minor.micro
+
+   Major = breaks backwards compatibility
+   minor = new features with backwards compatibility
+   micro = bug fixes with backwards compatibility
+
+ - Migration code for v17 or older users has been removed.
+
+   During testing, it was apparent that the migration code wasn't working to
+   begin with. The major distros (Debian, RedHat) have already moved to v18+ for
+   LTS. Rolling release distros and Homebrew / Macports are regularly kept up to
+   date.
+
+   Users upgrading from v17 or older will start with a new database.
+
+ - Approximate matching introduced.
+
+   Matching priority is now:
+   1. exact match
+   2. case insensitive match
+   3. approximate match
+
+ - The `j` function now accepts autojump arguments (e.g. --help, --stat).
+
+   As a result, the `jumpstat` alias is now removed. The preferred method is `j
+   --stat` or `j -s`. Consequently, autojump cannot jump to directories
+   beginning with a hyphen '-'.
+
+ - Always use case insensitive search with AUTOJUMP_IGNORE_CASE=1
+
+   As mentioned earlier, normal priority is to prefer exact match and then check
+   for case insensitive match. For users who prefer case insensitivity can now
+   modify the program behavior.
+
+ - Prevent database decay with AUTOJUMP_KEEP_ALL_ENTRIES=1
+
+   The database is regularly trimmed for performance reasons. However users can
+   prevent database maintenance with the above environmental variable.
+
+ - Database entry weight growth changed form linear to logarithmic scale.
+
+   A combination of low total weight ceiling and linear growth resulted in
+   a few, commonly used directories to be responsible for 50%+ of the total
+   database weight. This caused unnecessary trimming of long tail entries.
+
+   Switching to logarithmic growth combined with regular decay meant that
+   commonly used directories still climbed database ranking appropriately with a
+   more even weight distribution.
+
+ - Unit testing suite added.
+
+ - Miscellaneous refactoring, bug fixes, documentation updates.
+
 * Release v20:
 
- - Python versions supported is now v2.7+ and v3.2+ due to rewrite using argparse.
- - Man page and --help has been overhauled to provide better documentation and usage scenarios.
+ - Python versions supported is now v2.7+ and v3.2+ due to rewrite using
+ argparse.
+
+ - Man page and --help has been overhauled to provide better documentation and
+ usage scenarios.
+
  - Installation scripts now act dependent on current environmental settings.
-   If run as root, will do a global install. Installation script also detects which version to install (bash or zsh) dependent on $SHELL.  Both of these behaviors can be overrode using --local/--global or --bash/--zsh arguments.
- - Uninstallation script added, will remove both global and local installations but ignores database.
- - Symlinks can be preserved as database entries, refer to man page for more details.
- - This change log added to better help package maintainers keep track of changes between releases.
+
+   If run as root, will do a global install. Installation script also detects
+ which version to install (bash or zsh) dependent on $SHELL.  Both of these
+ behaviors can be overrode using --local/--global or --bash/--zsh arguments.
+
+ - Uninstallation script added, will remove both global and local installations
+ but ignores database.
+
+ - Allow symlink database entries with AUTOJUMP_KEEP_SYMLINKS=1
+
+   Normally symlinks are resolved to full path to prevent duplicate database
+   entries. However users who prefer symlink paths can modify behavior with the
+   above environmental variable.
+
+ - This change log added to better help package maintainers keep track of
+ changes between releases.
+
  - Miscellaneous bug fixes.
 
 * Release v19:

README.md

@@ -176,6 +176,18 @@ ADDITIONAL CONFIGURATION
 ADVANCED USAGE
 --------------
 
+-   Using Multiple Arguments
+
+    Let's assume the following database:
+
+        30   /home/user/mail/inbox
+        10   /home/user/work/inbox
+
+    `j in` would jump into /home/user/mail/inbox as the higher weighted
+    entry. However you can pass multiple arguments to autojump to prefer
+    a different entry. In the above example, `j w in` would then jump
+    you into /home/user/work/inbox.
+
 -   Change Directory Weight
 
     To manually change a directory's key weight, you can edit the file
@@ -193,10 +205,6 @@ KNOWN ISSUES
     `-`. If you want to jump a directory called `--music`, try using
     `j music` instead of `j --music`.
 
--   zsh (bug \#86)
-
-    Tab completion does not work.
-
 -   jumpapplet (bug \#59)
 
     Does not work in Gnome 3 shell or LDXE.

bin/autojump

@@ -29,7 +29,7 @@ import shutil
 import sys
 from tempfile import NamedTemporaryFile
 
-VERSION = 'release-v20.9.5'
+VERSION = 'release-v21-rc'
 MAX_KEYWEIGHT = 1000
 MAX_STORED_PATHS = 1000
 COMPLETION_SEPARATOR = '__'

docs/autojump.1

@@ -103,6 +103,26 @@ export\ AUTOJUMP_KEEP_SYMLINKS=1
 .RE
 .SS ADVANCED USAGE
 .IP \[bu] 2
+Using Multiple Arguments
+.RS 2
+.PP
+Let\[aq]s assume the following database:
+.IP
+.nf
+\f[C]
+30\ \ \ /home/user/mail/inbox
+10\ \ \ /home/user/work/inbox
+\f[]
+.fi
+.PP
+\f[C]j\ in\f[] would jump into /home/user/mail/inbox as the higher
+weighted entry.
+However you can pass multiple arguments to autojump to prefer a
+different entry.
+In the above example, \f[C]j\ w\ in\f[] would then jump you into
+/home/user/work/inbox.
+.RE
+.IP \[bu] 2
 Change Directory Weight
 .RS 2
 .PP
@@ -126,12 +146,6 @@ with \f[C]-\f[].
 If you want to jump a directory called \f[C]--music\f[], try using
 \f[C]j\ music\f[] instead of \f[C]j\ --music\f[].
 .IP \[bu] 2
-zsh (bug #86)
-.RS 2
-.PP
-Tab completion does not work.
-.RE
-.IP \[bu] 2
 jumpapplet (bug #59)
 .RS 2
 .PP

docs/body.md

@@ -38,6 +38,15 @@ Options must be passed to 'autojump' and not the 'j' wrapper function.
 
 ## ADVANCED USAGE
 
+- Using Multiple Arguments
+
+    Let's assume the following database:
+
+        30   /home/user/mail/inbox
+        10   /home/user/work/inbox
+
+    `j in` would jump into /home/user/mail/inbox as the higher weighted entry. However you can pass multiple arguments to autojump to prefer a different entry. In the above example, `j w in` would then jump you into /home/user/work/inbox.
+
 - Change Directory Weight
 
     To manually change a directory's key weight, you can edit the file _$XDG_DATA_HOME/autojump/autojump.txt_. Each entry has two columns. The first is the key weight and the second is the path:
@@ -50,10 +59,6 @@ Options must be passed to 'autojump' and not the 'j' wrapper function.
 
 - The jump function `j` does not support directories that begin with `-`. If you want to jump a directory called `--music`, try using `j music` instead of `j --music`.
 
-- zsh (bug #86)
-
-    Tab completion does not work.
-
 - jumpapplet (bug #59)
 
     Does not work in Gnome 3 shell or LDXE.