From 1a0003d852523ccb97702ede11c672ea74d985a6 Mon Sep 17 00:00:00 2001
From: William Ting <io@williamting.com>
Date: Tue, 7 Jan 2014 11:44:44 -0600
Subject: [PATCH 1/4] Fix encoding issues.

The original implementation used str.encode() on input and str.decode() on
output. However this would cause UnicodeDecodeError since certain characters
can't be encoded / decoded in ASCII.

The new solution is to use unicode() on all input strings and output UTF-8
encoded strings. This makes the assumption that the shell can handle UTF-8
strings.
---
 bin/autojump                 | 21 +++++++++------------
 bin/autojump_data.py         |  7 ++-----
 bin/autojump_utils.py        | 31 ++++++++-----------------------
 tests/autojump_utils_test.py |  9 +++++----
 4 files changed, 24 insertions(+), 44 deletions(-)

diff --git a/bin/autojump b/bin/autojump
index 82a2bb3..77de9da 100755
--- a/bin/autojump
+++ b/bin/autojump
@@ -45,8 +45,7 @@ from autojump_data import entriefy
 from autojump_data import Entry
 from autojump_data import load
 from autojump_data import save
-from autojump_utils import decode
-from autojump_utils import encode_local
+from autojump_utils import encode
 from autojump_utils import first
 from autojump_utils import get_tab_entry_info
 from autojump_utils import get_pwd
@@ -131,7 +130,7 @@ def add_path(data, path, weight=10):
     with resulting duplicate entries in the database than a single canonical
     path.
     """
-    path = decode(path).rstrip(os.sep)
+    path = encode(path).rstrip(os.sep)
     if path == os.path.expanduser('~'):
         return data, Entry(path, 0)
 
@@ -142,7 +141,7 @@ def add_path(data, path, weight=10):
 
 def decrease_path(data, path, weight=15):
     """Decrease or zero out a path."""
-    path = decode(path).rstrip(os.sep)
+    path = encode(path).rstrip(os.sep)
     data[path] = max(0, data.get(path, 0) - weight)
     return data, Entry(path, data[path])
 
@@ -189,11 +188,10 @@ def handle_tab_completion(needle, entries):
     tab_needle, tab_index, tab_path = get_tab_entry_info(needle, TAB_SEPARATOR)
 
     if tab_path:
-        print(encode_local(tab_path))
+        print(tab_path)
     elif tab_index:
         get_ith_path = lambda i, iterable: last(take(i, iterable)).path
-        print(encode_local(
-            get_ith_path(tab_index, find_matches(entries, tab_needle))))
+        print(get_ith_path(tab_index, find_matches(entries, tab_needle)))
     elif tab_needle:
         # found partial tab completion entry
         print_tab_menu(
@@ -362,7 +360,7 @@ def main(args):  # noqa
     elif not args.directory:
         # default return value so calling shell functions have an argument
         # to `cd` to
-        print(encode_local('.'))
+        print('.')
     else:
         entries = entriefy(load(config))
         needles = sanitize(args.directory)
@@ -370,13 +368,12 @@ def main(args):  # noqa
             get_tab_entry_info(first(needles), TAB_SEPARATOR)
 
         if tab_path:
-            print(encode_local(tab_path))
+            print(tab_path)
         elif tab_index:
             get_ith_path = lambda i, iterable: last(take(i, iterable)).path
-            print(encode_local(
-                get_ith_path(tab_index, find_matches(entries, tab_needle))))
+            print(get_ith_path(tab_index, find_matches(entries, tab_needle)))
         else:
-            print(encode_local(first(find_matches(entries, needles)).path))
+            print(first(find_matches(entries, needles)).path)
 
     return 0
 
diff --git a/bin/autojump_data.py b/bin/autojump_data.py
index 9b806a6..4afad6d 100644
--- a/bin/autojump_data.py
+++ b/bin/autojump_data.py
@@ -17,6 +17,7 @@ else:
     from itertools import imap
 
 from autojump_utils import create_dir
+from autojump_utils import encode
 from autojump_utils import is_osx
 from autojump_utils import is_python3
 from autojump_utils import move_file
@@ -124,11 +125,7 @@ def save(config, data):
                 encoding='utf-8',
                 errors='replace') as f:
             for path, weight in data.items():
-                if is_python3():
-                    f.write(("%s\t%s\n" % (weight, path)))
-                else:
-                    f.write(unicode(
-                        "%s\t%s\n" % (weight, path)).encode('utf-8'))
+                f.write(encode("%s\t%s\n" % (weight, path)))
 
             f.flush()
             os.fsync(f)
diff --git a/bin/autojump_utils.py b/bin/autojump_utils.py
index 1d88e1d..e0313ed 100644
--- a/bin/autojump_utils.py
+++ b/bin/autojump_utils.py
@@ -28,26 +28,10 @@ def create_dir(path):
             raise
 
 
-def decode(string):
-    """Converts byte string to Unicode string."""
-    if is_python2():
-        # Python 2.6 does not support kwargs
-        return string.decode('utf-8', 'replace')
-    return string
-
-
 def encode(string):
-    """Converts Unicode string to byte string."""
-    if is_python2():
-        # Python 2.6 does not support kwargs
-        return string.encode('utf-8', 'replace')
-    return string
-
-
-def encode_local(string, encoding=None):
-    """Converts string into local filesystem encoding."""
-    if is_python2():
-        return decode(string).encode(encoding or sys.getfilesystemencoding())
+    """Converts into Unicode string."""
+    if is_python2() and not isinstance(string, unicode):
+        return unicode(string, encoding='utf-8', errors='replace')
     return string
 
 
@@ -153,7 +137,7 @@ def move_file(src, dst):
 
 
 def print_entry(entry):
-    print(encode_local("%.1f:\t%s" % (entry.weight, entry.path)))
+    print("%.1f:\t%s" % (entry.weight, entry.path))
 
 
 def print_tab_menu(needle, tab_entries, separator):
@@ -166,17 +150,18 @@ def print_tab_menu(needle, tab_entries, separator):
     on subsequent calls.
     """
     for i, entry in enumerate(tab_entries):
-        print(encode_local(
+        print(
             '%s%s%d%s%s' % (
                 needle,
                 separator,
                 i + 1,
                 separator,
-                entry.path)))
+                entry.path))
 
 
 def sanitize(directories):
-    clean = lambda x: decode(x) if len(x) == 1 else decode(x).rstrip(os.sep)
+    # edge case to allow '/' as a valid path
+    clean = lambda x: encode(x) if x == os.sep else encode(x).rstrip(os.sep)
     return list(imap(clean, directories))
 
 
diff --git a/tests/autojump_utils_test.py b/tests/autojump_utils_test.py
index 235d5d9..a20298e 100644
--- a/tests/autojump_utils_test.py
+++ b/tests/autojump_utils_test.py
@@ -20,7 +20,7 @@ from testify import teardown
 
 import autojump_utils
 from autojump_utils import create_dir
-from autojump_utils import decode
+from autojump_utils import encode
 from autojump_utils import first
 from autojump_utils import get_pwd
 from autojump_utils import get_tab_entry_info
@@ -35,9 +35,10 @@ from autojump_utils import take
 
 
 class StringUnitTests(TestCase):
-    def test_decode(self):
-        assert_equal(decode(r'blah'), u'blah')
-        assert_equal(decode(r'日本語'), u'日本語')
+    def test_encode(self):
+        assert_equal(encode(b'blah'), u'blah')
+        assert_equal(encode(b'日本語'), u'日本語')
+        assert_equal(encode(u'でもおれは中国人だ。'), u'でもおれは中国人だ。')
 
     def test_has_uppercase(self):
         assert_true(has_uppercase('Foo'))

From de85828b796c779f0e8d6537230e28e974362624 Mon Sep 17 00:00:00 2001
From: William Ting <io@williamting.com>
Date: Tue, 7 Jan 2014 12:32:35 -0600
Subject: [PATCH 2/4] update documentation

---
 Makefile               |   2 +-
 README.md              | 257 ++++++++++-------------------------------
 docs/autojump.1        | 191 +++++++-----------------------
 docs/body.md           | 135 +++-------------------
 docs/development.md    |   9 --
 docs/header.md         |  57 +++++++--
 docs/install.md        |  59 +++-------
 docs/manpage_header.md |   2 +-
 install.py             |   4 +-
 9 files changed, 182 insertions(+), 534 deletions(-)
 delete mode 100644 docs/development.md

diff --git a/Makefile b/Makefile
index 5eb2329..07bb52b 100644
--- a/Makefile
+++ b/Makefile
@@ -11,7 +11,7 @@ uninstall:
 
 docs:
 	pandoc -s -w man docs/manpage_header.md docs/header.md docs/body.md -o docs/autojump.1
-	pandoc -s -w markdown docs/header.md docs/install.md docs/development.md docs/body.md -o README.md
+	pandoc -s -w markdown docs/header.md docs/install.md docs/body.md -o README.md
 
 lint:
 	@flake8 ./ --config=setup.cfg
diff --git a/README.md b/README.md
index 8d4612a..d876c1e 100644
--- a/README.md
+++ b/README.md
@@ -3,137 +3,46 @@ NAME
 
 autojump - a faster way to navigate your filesystem
 
-SYNOPSIS
---------
-
-Jump to a previously visited directory that contains 'foo':
-
-    j foo
-
-Jump to a previously visited subdirectory of the current directory:
-
-    jc bar
-
-Show database entries and their respective key weights:
-
-    j --stat
-
 DESCRIPTION
 -----------
 
 autojump is a faster way to navigate your filesystem. It works by
 maintaining a database of the directories you use the most from the
-command line. Directories must be visited first before they can be
-jumped to.
-
-INSTALLATION
-------------
-
-### REQUIREMENTS
-
--   Python v2.6+
--   Bash v4.0 for tab completion (or zsh)
-
-If you are unable to update Python to a supported version, older
-versions of autojump can be [downloaded][dl] and installed manually.
-
--   Python v2.4 is supported by [release v12][v12].
-
-### AUTOMATIC INSTALLATION
-
-**Linux**
-
-autojump is included in the following distro repositories, please use
-relevant package management utilities to install (e.g. yum, apt-get,
-etc):
-
--   Debian\* testing/unstable, Ubuntu, Linux Mint
--   RedHat, Fedora, CentOS
--   ArchLinux
--   Gentoo
--   Frugalware
--   Slackware
+command line.
 
-\* Requires manual activation for policy reasons, please see
-`/usr/share/doc/autojump/README.Debian`.
+*Directories must be visited first before they can be jumped to.*
 
-**Mac**
-
-Homebrew is the recommended installation method for Mac OS X:
-
-    brew install autojump
-
-MacPorts also available:
-
-    port install autojump
-
-**Other**
-
-Please check the [Wiki][wiki] for an up to date listing of installation methods.
-
-### MANUAL INSTALLATION
-
-Grab a copy of autojump:
-
-    git clone git://github.com/joelthelion/autojump.git
-
-Run the installation script:
-
-    cd autojump
-    ./install.sh [ --local ]
-
-and follow on screen instructions.
-
-### MANUAL UNINSTALLATION
-
-It is recommended to use your distribution's relevant package management
-utilities, unless you installed manually or ran into uninstallation
-issues.
-
-Grab a copy of autojump:
-
-    git clone git://github.com/joelthelion/autojump.git
-
-Run the uninstallation script:
-
-    cd autojump
-    ./uninstall.sh
-
-and follow on screen instructions.
-
-If you keep getting `autojump: command not found` at the prompt,
-do:`unset PROMPT_COMMAND`. You can also restart your shell.
-
-DEVELOPMENT
------------
+USAGE
+-----
 
-The source code is primarily in `./bin/autojump`. Various shell wrapper
-scripts are also available in `./bin/`.
+`j` is a convenience wrapper function around `autojump`. Any option that
+can be used with `autojump` can be used with `j` and vice versa.
 
-Documentation is in various files under `./docs/`. Build documentation
-with the command:
+-   Jump To A Directory That Contains `foo`:
 
-    make docs
+        j foo
 
-OPTIONS
--------
+-   Jump To A Child Directory
 
-Options must be passed to 'autojump' and not the 'j' wrapper function.
+    Sometimes it's convenient to jump to a child directory
+    (sub-directory of current directory) rather than typing out the full
+    name.
 
-    -i, --increase      manually increase current directory weight
+        jc bar
 
-    -d, --decrease      manually decrease current directory weight
+-   Open File Manager To Directories (instead of jumping):
 
-    --purge             deletes database entries that no longer exist on system
+    Instead of jumping to a directory, you can open a file explorer
+    window (Mac Finder, Windows Explorer, GNOME Nautilus, etc.) to the
+    directory instead.
 
-    -s, --stat          show general stats and top 100 database entries
+        jo music
 
-    --version           show version information and exit
+    Opening a file manager to a child directory is also supported.
 
-ADVANCED USAGE
---------------
+        jco images
 
--   Using Multiple Arguments
+-   Using Multiple Arguments:
 
     Let's assume the following database:
 
@@ -142,132 +51,92 @@ ADVANCED USAGE
 
     `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.
-
--   Jump To A Child Directory.
-
-    Sometimes it's convenient to jump to a child directory
-    (sub-directory of current directory) rather than typing out the full
-    name.
-
-        jc images
+    a different entry. In the above example, `j w in` would then change
+    directory to /home/user/work/inbox.
 
--   Open File Manager To Directories (instead of jumping)
+For more options refer to help:
 
-    Instead of jumping to a directory, you can open a file explorer
-    window (Mac Finder, Windows Explorer, GNOME Nautilus, etc) to the
-    directory instead.
-
-        jo music
+    autojump --help
 
-    Opening a file manager to a child directory is also supported.
+INSTALLATION
+------------
 
-        jco images
+### REQUIREMENTS
 
-ADDITIONAL CONFIGURATION
-------------------------
+-   Python v2.6+
+-   Bash v4.0+, zsh, or fish
 
--   Enable ZSH Tab Completion
+### AUTOMATIC
 
-    ZSH tab completion requires the `compinit` module to be loaded.
-    Please add the following line to your \~/.zshrc *after* loading
-    autojump:
+#### Linux
 
-        autoload -U compinit && compinit
+autojump is included in the following distro repositories, please use
+relevant package management utilities to install (e.g. yum, apt-get,
+etc):
 
-    For security compinit checks completion system if files will be
-    owned by root or the current user. This check can be ignored by
-    using the -u flag:
+-   Debian testing/unstable, Ubuntu, Linux Mint
 
-        autoload -U compinit && compinit -u
+    All Debian-derived distros require manual activation for policy
+    reasons, please see `/usr/share/doc/autojump/README.Debian`.
 
-    Tab completion requires two tabs before autojump will display the
-    completion menu. However if `setopt nolistambiguous` is enabled,
-    then only one tab is required.
+-   RedHat, Fedora, CentOS
+-   ArchLinux
+-   Gentoo
+-   Frugalware
+-   Slackware
 
--   Always Ignore Case
+#### OS X
 
-    Default behavior is to prioritize exact matches over all else. For
-    example, `j foo` will prefer /foobar over /FooBar even if the latter
-    has a higher weight. To change this behavior and ignore case, add
-    the following environmental variable in your \~/.bashrc:
+Homebrew is the recommended installation method for Mac OS X:
 
-        export AUTOJUMP_IGNORE_CASE=1
+    brew install autojump
 
--   Prefer Symbolic Links
+MacPorts also available:
 
-    Default behavior is to evaluate symbolic links into full paths as to
-    reduce duplicate entries in the database. However, some users prefer
-    a shorter working directory path in their shell prompt. To switch
-    behavior to prefer symbolic links, add the following environmental
-    variable in your \~/.bashrc:
+    port install autojump
 
-        export AUTOJUMP_KEEP_SYMLINKS=1
+### MANUAL
 
--   Autocomplete Additional Commands (Bash only)
+Grab a copy of autojump:
 
-    Autojump can be used to autocomplete other commands (e.g. cp or
-    vim). To use this feature, add the following environmental variable
-    in your \~/.bashrc:
+    git clone git://github.com/joelthelion/autojump.git
 
-        export AUTOJUMP_AUTOCOMPLETE_CMDS='cp vim'
+Run the installation script and follow on screen instructions.
 
-    Changes require reloading autojump to take into effect.
+    cd autojump
+    ./install.py or ./uinstall.py
 
 KNOWN ISSUES
 ------------
 
--   For bash users, autojump keeps track of directories as a pre-command
-    hook by modifying \$PROMPT\_COMMAND. If you overwrite
-    \$PROMPT\_COMMAND in \~/.bashrc you can cause problems. Don't do
-    this:
+-   autojump does not support directories that begin with `-`.
+
+-   For bash users, autojump keeps track of directories by modifying
+    `$PROMPT_COMMAND`. Do not overwrite `$PROMPT_COMMAND`:
 
         export PROMPT_COMMAND="history -a"
 
-    Do this:
+    Instead append to the end of the existing $PROMPT\_COMMAND:
 
         export PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND ;} history -a"
 
--   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`.
-
-FILES
------
-
-If installed locally, autojump is self-contained in *\~/.autojump/*.
-
-The database is stored in *\$XDG\_DATA\_HOME/autojump/autojump.txt*.
-
 REPORTING BUGS
 --------------
 
-For any usage related issues or feature requests please visit:
+For any questions or issues please visit:
 
-*https://github.com/joelthelion/autojump/issues*
-
-THANKS
-------
-
-Special thanks goes out to: Pierre Gueth, Simon Marache-Francisco,
-Daniel Jackoway, and many others.
+    https://github.com/joelthelion/autojump/issues
 
 AUTHORS
 -------
 
 autojump was originally written by Joël Schaerer, and currently
-maintained by William Ting.
+maintained by William Ting. More contributors can be found in `AUTHORS`.
 
 COPYRIGHT
 ---------
 
-Copyright © 2013 Free Software Foundation, Inc. License GPLv3+: GNU GPL
+Copyright © 2012 Free Software Foundation, Inc. License GPLv3+: GNU GPL
 version 3 or later <http://gnu.org/licenses/gpl.html>. This is free
 software: you are free to change and redistribute it. There is NO
 WARRANTY, to the extent permitted by law.
-
-[dl]: https://github.com/joelthelion/autojump/downloads
-[mock]: https://pypi.python.org/pypi/mock
-[v12]: https://github.com/downloads/joelthelion/autojump/autojump_v12.tar.gz
-[wiki]: https://github.com/joelthelion/autojump/wiki
diff --git a/docs/autojump.1 b/docs/autojump.1
index ee50393..d3c8d25 100644
--- a/docs/autojump.1
+++ b/docs/autojump.1
@@ -1,98 +1,50 @@
-.TH autojump 1 "10 April 2012" "release\-v20"
+.TH autojump 1 "10 April 2012" "release-v22"
 .SS NAME
 .PP
-autojump \- a faster way to navigate your filesystem
-.SS SYNOPSIS
-.PP
-Jump to a previously visited directory that contains \[aq]foo\[aq]:
-.IP
-.nf
-\f[C]
-j\ foo
-\f[]
-.fi
-.PP
-Jump to a previously visited subdirectory of the current directory:
-.IP
-.nf
-\f[C]
-jc\ bar
-\f[]
-.fi
-.PP
-Show database entries and their respective key weights:
-.IP
-.nf
-\f[C]
-j\ \-\-stat
-\f[]
-.fi
+autojump - a faster way to navigate your filesystem
 .SS DESCRIPTION
 .PP
 autojump is a faster way to navigate your filesystem.
 It works by maintaining a database of the directories you use the most
 from the command line.
-Directories must be visited first before they can be jumped to.
-.SS OPTIONS
 .PP
-Options must be passed to \[aq]autojump\[aq] and not the \[aq]j\[aq]
-wrapper function.
-.IP
-.nf
-\f[C]
-\-i,\ \-\-increase\ \ \ \ \ \ manually\ increase\ current\ directory\ weight
-
-\-d,\ \-\-decrease\ \ \ \ \ \ manually\ decrease\ current\ directory\ weight
-
-\-\-purge\ \ \ \ \ \ \ \ \ \ \ \ \ deletes\ database\ entries\ that\ no\ longer\ exist\ on\ system
-
-\-s,\ \-\-stat\ \ \ \ \ \ \ \ \ \ show\ general\ stats\ and\ top\ 100\ database\ entries
-
-\-\-version\ \ \ \ \ \ \ \ \ \ \ show\ version\ information\ and\ exit
-\f[]
-.fi
-.SS ADVANCED USAGE
+\f[I]Directories must be visited first before they can be jumped to.\f[]
+.SS USAGE
+.PP
+\f[C]j\f[] is a convenience wrapper function around \f[C]autojump\f[].
+Any option that can be used with \f[C]autojump\f[] can be used with
+\f[C]j\f[] and vice versa.
 .IP \[bu] 2
-Using Multiple Arguments
+Jump To A Directory That Contains \f[C]foo\f[]:
 .RS 2
-.PP
-Let\[aq]s assume the following database:
 .IP
 .nf
 \f[C]
-30\ \ \ /home/user/mail/inbox
-10\ \ \ /home/user/work/inbox
+j\ foo
 \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
-Jump To A Child Directory.
+Jump To A Child Directory
 .RS 2
 .PP
 Sometimes it\[aq]s convenient to jump to a child directory
-(sub\-directory of current directory) rather than typing out the full
+(sub-directory of current directory) rather than typing out the full
 name.
 .IP
 .nf
 \f[C]
-jc\ images
+jc\ bar
 \f[]
 .fi
 .RE
 .IP \[bu] 2
-Open File Manager To Directories (instead of jumping)
+Open File Manager To Directories (instead of jumping):
 .RS 2
 .PP
 Instead of jumping to a directory, you can open a file explorer window
-(Mac Finder, Windows Explorer, GNOME Nautilus, etc) to the directory
-instead.
+(Mac Finder, Windows Explorer, GNOME Nautilus, etc.)
+ to the directory instead.
 .IP
 .nf
 \f[C]
@@ -108,132 +60,71 @@ jco\ images
 \f[]
 .fi
 .RE
-.SS ADDITIONAL CONFIGURATION
 .IP \[bu] 2
-Enable ZSH Tab Completion
+Using Multiple Arguments:
 .RS 2
 .PP
-ZSH tab completion requires the \f[C]compinit\f[] module to be loaded.
-Please add the following line to your ~/.zshrc \f[I]after\f[] loading
-autojump:
-.IP
-.nf
-\f[C]
-autoload\ \-U\ compinit\ &&\ compinit
-\f[]
-.fi
-.PP
-For security compinit checks completion system if files will be owned by
-root or the current user.
-This check can be ignored by using the \-u flag:
+Let\[aq]s assume the following database:
 .IP
 .nf
 \f[C]
-autoload\ \-U\ compinit\ &&\ compinit\ \-u
+30\ \ \ /home/user/mail/inbox
+10\ \ \ /home/user/work/inbox
 \f[]
 .fi
 .PP
-Tab completion requires two tabs before autojump will display the
-completion menu.
-However if \f[C]setopt\ nolistambiguous\f[] is enabled, then only one
-tab is required.
+\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 change directory to
+/home/user/work/inbox.
 .RE
-.IP \[bu] 2
-Always Ignore Case
-.RS 2
 .PP
-Default behavior is to prioritize exact matches over all else.
-For example, \f[C]j\ foo\f[] will prefer /foobar over /FooBar even if
-the latter has a higher weight.
-To change this behavior and ignore case, add the following environmental
-variable in your ~/.bashrc:
+For more options refer to help:
 .IP
 .nf
 \f[C]
-export\ AUTOJUMP_IGNORE_CASE=1
+autojump\ --help
 \f[]
 .fi
-.RE
+.SS KNOWN ISSUES
 .IP \[bu] 2
-Prefer Symbolic Links
-.RS 2
-.PP
-Default behavior is to evaluate symbolic links into full paths as to
-reduce duplicate entries in the database.
-However, some users prefer a shorter working directory path in their
-shell prompt.
-To switch behavior to prefer symbolic links, add the following
-environmental variable in your ~/.bashrc:
-.IP
-.nf
-\f[C]
-export\ AUTOJUMP_KEEP_SYMLINKS=1
-\f[]
-.fi
-.RE
+autojump does not support directories that begin with \f[C]-\f[].
 .IP \[bu] 2
-Autocomplete Additional Commands (Bash only)
+For bash users, autojump keeps track of directories by modifying
+\f[C]$PROMPT_COMMAND\f[].
+Do not overwrite \f[C]$PROMPT_COMMAND\f[]:
 .RS 2
-.PP
-Autojump can be used to autocomplete other commands (e.g.
-cp or vim).
-To use this feature, add the following environmental variable in your
-~/.bashrc:
 .IP
 .nf
 \f[C]
-export\ AUTOJUMP_AUTOCOMPLETE_CMDS=\[aq]cp\ vim\[aq]
+export\ PROMPT_COMMAND="history\ -a"
 \f[]
 .fi
 .PP
-Changes require reloading autojump to take into effect.
-.RE
-.SS KNOWN ISSUES
-.IP \[bu] 2
-For bash users, autojump keeps track of directories as a pre\-command
-hook by modifying $PROMPT_COMMAND.
-If you overwrite $PROMPT_COMMAND in ~/.bashrc you can cause problems.
-Don\[aq]t do this:
-.RS 2
+Instead append to the end of the existing $PROMPT_COMMAND:
 .IP
 .nf
 \f[C]
-export\ PROMPT_COMMAND="history\ \-a"
+export\ PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND\ ;}\ history\ -a"
 \f[]
 .fi
+.RE
+.SS REPORTING BUGS
 .PP
-Do this:
+For any questions or issues please visit:
 .IP
 .nf
 \f[C]
-export\ PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND\ ;}\ history\ \-a"
+https://github.com/joelthelion/autojump/issues
 \f[]
 .fi
-.RE
-.IP \[bu] 2
-The jump function \f[C]j\f[] does not support directories that begin
-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[].
-.SS FILES
-.PP
-If installed locally, autojump is self\-contained in
-\f[I]~/.autojump/\f[].
-.PP
-The database is stored in \f[I]$XDG_DATA_HOME/autojump/autojump.txt\f[].
-.SS REPORTING BUGS
-.PP
-For any usage related issues or feature requests please visit:
-.PP
-\f[I]https://github.com/joelthelion/autojump/issues\f[]
-.SS THANKS
-.PP
-Special thanks goes out to: Pierre Gueth, Simon Marache\-Francisco,
-Daniel Jackoway, and many others.
 .SS AUTHORS
 .PP
 autojump was originally written by Joël Schaerer, and currently
 maintained by William Ting.
+More contributors can be found in \f[C]AUTHORS\f[].
 .SS COPYRIGHT
 .PP
 Copyright © 2012 Free Software Foundation, Inc.
diff --git a/docs/body.md b/docs/body.md
index 1b12205..9d635b4 100644
--- a/docs/body.md
+++ b/docs/body.md
@@ -1,137 +1,32 @@
-## OPTIONS
+KNOWN ISSUES
+------------
 
-Options must be passed to 'autojump' and not the 'j' wrapper function.
+-   autojump does not support directories that begin with `-`.
 
-    -i, --increase      manually increase current directory weight
-
-    -d, --decrease      manually decrease current directory weight
-
-    --purge             deletes database entries that no longer exist on system
-
-    -s, --stat          show general stats and top 100 database entries
-
-    --version           show version information and exit
-
-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.
-
--   Jump To A Child Directory.
-
-    Sometimes it's convenient to jump to a child directory (sub-directory of
-    current directory) rather than typing out the full name.
-
-        jc images
-
--   Open File Manager To Directories (instead of jumping)
-
-    Instead of jumping to a directory, you can open a file explorer window (Mac
-    Finder, Windows Explorer, GNOME Nautilus, etc) to the directory instead.
-
-        jo music
-
-    Opening a file manager to a child directory is also supported.
-
-        jco images
-
-ADDITIONAL CONFIGURATION
-------------------------
-
--   Enable ZSH Tab Completion
-
-    ZSH tab completion requires the `compinit` module to be loaded.
-    Please add the following line to your \~/.zshrc *after* loading autojump:
-
-        autoload -U compinit && compinit
-
-    For security compinit checks completion system if files will be owned by
-    root or the current user. This check can be ignored by using the -u flag:
-
-        autoload -U compinit && compinit -u
-
-    Tab completion requires two tabs before autojump will display the
-    completion menu. However if `setopt nolistambiguous` is enabled,
-    then only one tab is required.
-
--   Always Ignore Case
-
-    Default behavior is to prioritize exact matches over all else. For
-    example, `j foo` will prefer /foobar over /FooBar even if the latter
-    has a higher weight. To change this behavior and ignore case, add
-    the following environmental variable in your \~/.bashrc:
-
-        export AUTOJUMP_IGNORE_CASE=1
-
--   Prefer Symbolic Links
-
-    Default behavior is to evaluate symbolic links into full paths as to
-    reduce duplicate entries in the database. However, some users prefer
-    a shorter working directory path in their shell prompt. To switch
-    behavior to prefer symbolic links, add the following environmental
-    variable in your \~/.bashrc:
-
-        export AUTOJUMP_KEEP_SYMLINKS=1
-
--   Autocomplete Additional Commands (Bash only)
-
-    Autojump can be used to autocomplete other commands (e.g. cp or
-    vim). To use this feature, add the following environmental variable
-    in your \~/.bashrc:
-
-        export AUTOJUMP_AUTOCOMPLETE_CMDS='cp vim'
-
-    Changes require reloading autojump to take into effect.
-
-## KNOWN ISSUES
-
-- For bash users, autojump keeps track of directories as a pre-command hook by
-  modifying \$PROMPT\_COMMAND. If you overwrite \$PROMPT\_COMMAND in ~/.bashrc you
-  can cause problems. Don't do this:
+-   For bash users, autojump keeps track of directories by modifying
+    `$PROMPT_COMMAND`. Do not overwrite `$PROMPT_COMMAND`:
 
         export PROMPT_COMMAND="history -a"
 
-    Do this:
+    Instead append to the end of the existing \$PROMPT\_COMMAND:
 
         export PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND ;} history -a"
 
-- 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`.
-
-## FILES
-
-If installed locally, autojump is self-contained in _~/.autojump/_.
-
-The database is stored in _$XDG\_DATA\_HOME/autojump/autojump.txt_.
-
-## REPORTING BUGS
-
-For any usage related issues or feature requests please visit:
-
-_https://github.com/joelthelion/autojump/issues_
+REPORTING BUGS
+--------------
 
-## THANKS
+For any questions or issues please visit:
 
-Special thanks goes out to: Pierre Gueth, Simon Marache-Francisco, Daniel
-Jackoway, and many others.
+    https://github.com/joelthelion/autojump/issues
 
-## AUTHORS
+AUTHORS
+-------
 
 autojump was originally written by Joël Schaerer, and currently maintained by
-William Ting.
+William Ting. More contributors can be found in `AUTHORS`.
 
-## COPYRIGHT
+COPYRIGHT
+---------
 
 Copyright © 2012 Free Software Foundation, Inc. License GPLv3+: GNU  GPL version
 3 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are
diff --git a/docs/development.md b/docs/development.md
deleted file mode 100644
index e0b1544..0000000
--- a/docs/development.md
+++ /dev/null
@@ -1,9 +0,0 @@
-## DEVELOPMENT
-
-The source code is primarily in `./bin/autojump`. Various shell wrapper scripts
-are also available in `./bin/`.
-
-Documentation is in various files under `./docs/`. Build documentation with the
-command:
-
-    make docs
diff --git a/docs/header.md b/docs/header.md
index adcb47f..09fc42c 100644
--- a/docs/header.md
+++ b/docs/header.md
@@ -1,23 +1,56 @@
-## NAME
+NAME
+----
 
 autojump - a faster way to navigate your filesystem
 
-## SYNOPSIS
+DESCRIPTION
+-----------
 
-Jump to a previously visited directory that contains 'foo':
+autojump is a faster way to navigate your filesystem. It works by maintaining a
+database of the directories you use the most from the command line.
 
-    j foo
+*Directories must be visited first before they can be jumped to.*
 
-Jump to a previously visited subdirectory of the current directory:
+USAGE
+-----
 
-    jc bar
+`j` is a convenience wrapper function around `autojump`. Any option that can
+be used with `autojump` can be used with `j` and vice versa.
 
-Show database entries and their respective key weights:
+- Jump To A Directory That Contains `foo`:
 
-    j --stat
+        j foo
 
-## DESCRIPTION
+- Jump To A Child Directory
 
-autojump is a faster way to navigate your filesystem. It works by maintaining a
-database of the directories you use the most from the command line. Directories
-must be visited first before they can be jumped to.
+    Sometimes it's convenient to jump to a child directory (sub-directory of
+    current directory) rather than typing out the full name.
+
+        jc bar
+
+- Open File Manager To Directories (instead of jumping):
+
+    Instead of jumping to a directory, you can open a file explorer window (Mac
+    Finder, Windows Explorer, GNOME Nautilus, etc.) to the directory instead.
+
+        jo music
+
+    Opening a file manager to a child directory is also supported.
+
+        jco images
+
+- 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 change
+    directory to /home/user/work/inbox.
+
+For more options refer to help:
+
+    autojump --help
diff --git a/docs/install.md b/docs/install.md
index 7dce2c6..ed0ee3d 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -2,32 +2,28 @@
 
 ### REQUIREMENTS
 
-- Python v2.7+
-- Bash v4.0 for tab completion (or zsh)
+- Python v2.6+
+- Bash v4.0+, zsh, or fish
 
-If you are unable to update Python to a supported version, older versions of
-autojump can be [downloaded][dl] and installed manually.
+### AUTOMATIC
 
-- Python v2.4 is supported by [release v12][v12].
-
-### AUTOMATIC INSTALLATION
-
-**Linux**
+#### Linux
 
 autojump is included in the following distro repositories, please use relevant
 package management utilities to install (e.g. yum, apt-get, etc):
 
-- Debian\* testing/unstable, Ubuntu, Linux Mint
+- Debian testing/unstable, Ubuntu, Linux Mint
+
+    All Debian-derived distros require manual activation for policy reasons,
+    please see `/usr/share/doc/autojump/README.Debian`.
+
 - RedHat, Fedora, CentOS
 - ArchLinux
 - Gentoo
 - Frugalware
 - Slackware
 
-\* Requires manual activation for policy reasons, please see
-``/usr/share/doc/autojump/README.Debian``.
-
-**Mac**
+#### OS X
 
 Homebrew is the recommended installation method for Mac OS X:
 
@@ -37,42 +33,13 @@ MacPorts also available:
 
     port install autojump
 
-**Other**
-
-Please check the [Wiki][wiki] for an up to date listing of installation methods.
-
-### MANUAL INSTALLATION
-
-Grab a copy of autojump:
-
-    git clone git://github.com/joelthelion/autojump.git
-
-Run the installation script:
-
-    cd autojump
-    ./install.sh [ --local ]
-
-and follow on screen instructions.
-
-### MANUAL UNINSTALLATION
-
-It is recommended to use your distribution's relevant package management
-utilities, unless you installed manually or ran into uninstallation issues.
+### MANUAL
 
 Grab a copy of autojump:
 
     git clone git://github.com/joelthelion/autojump.git
 
-Run the uninstallation script:
+Run the installation script and follow on screen instructions.
 
     cd autojump
-    ./uninstall.sh
-
-and follow on screen instructions.
-
-If you keep getting `autojump: command not found` at the prompt, do:`unset
-PROMPT_COMMAND`. You can also restart your shell.
-
-[dl]: https://github.com/joelthelion/autojump/downloads
-[v12]: https://github.com/downloads/joelthelion/autojump/autojump_v12.tar.gz
-[wiki]: https://github.com/joelthelion/autojump/wiki
+    ./install.py or ./uinstall.py
diff --git a/docs/manpage_header.md b/docs/manpage_header.md
index 9311111..14e1938 100644
--- a/docs/manpage_header.md
+++ b/docs/manpage_header.md
@@ -1,3 +1,3 @@
-% autojump(1) release-v20
+% autojump(1) release-v22
 %
 % 10 April 2012
diff --git a/install.py b/install.py
index d1d5a6d..b296fb9 100755
--- a/install.py
+++ b/install.py
@@ -124,8 +124,10 @@ def print_post_installation_message(etc_dir):
         else:
             rcfile = '~/.%src' % get_shell()
 
-    print("\nPlease manually add the following line to %s:" % rcfile)
+    print("\nPlease manually add the following line(s) to %s:" % rcfile)
     print('\n\t' + source_msg)
+    if get_shell() == 'zsh':
+        print("\n\tautoload -U compinit && compinit -u")
     print("\nPlease restart terminal(s) before running autojump.\n")
 
 

From 47164936813e952e5b1266ec7ad331e159b5abbf Mon Sep 17 00:00:00 2001
From: William Ting <io@williamting.com>
Date: Tue, 7 Jan 2014 22:13:01 -0600
Subject: [PATCH 3/4] append error log if stuff breaks

---
 bin/autojump.bash | 12 +++++++++++-
 bin/autojump.fish |  1 +
 bin/autojump.zsh  | 11 +++++++++--
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/bin/autojump.bash b/bin/autojump.bash
index 3451f49..6447900 100644
--- a/bin/autojump.bash
+++ b/bin/autojump.bash
@@ -4,6 +4,16 @@ if [ -d ~/.autojump/ ]; then
 fi
 
 
+# set error file location
+if [[ "$(uname)" == "Darwin" ]]; then
+    export AUTOJUMP_ERROR_PATH=~/Library/autojump/errors.log
+elif [[ -n "${XDG_DATA_HOME}" ]]; then
+    export AUTOJUMP_ERROR_PATH="${XDG_DATA_HOME}/autojump/errors.log"
+else
+    export AUTOJUMP_ERROR_PATH=~/.local/share/autojump/errors.log
+fi
+
+
 # enable tab completion
 _autojump() {
         local cur
@@ -20,7 +30,7 @@ complete -F _autojump j
 
 # change pwd hook
 autojump_add_to_database() {
-    (autojump -a "$(pwd)" &) &>/dev/null
+    (autojump --add "$(pwd)" >/dev/null 2>${AUTOJUMP_ERROR_PATH} &) &>/dev/null
 }
 
 case $PROMPT_COMMAND in
diff --git a/bin/autojump.fish b/bin/autojump.fish
index f31f1df..aa0de49 100644
--- a/bin/autojump.fish
+++ b/bin/autojump.fish
@@ -17,6 +17,7 @@ end
 
 # misc helper functions
 function __aj_err
+    # TODO(ting|2014-01-07): set error file location
     echo $argv 1>&2; false
 end
 
diff --git a/bin/autojump.zsh b/bin/autojump.zsh
index 51a03a4..80c09b4 100644
--- a/bin/autojump.zsh
+++ b/bin/autojump.zsh
@@ -11,12 +11,19 @@ command -v brew &>/dev/null \
     && fpath=(`brew --prefix`/share/zsh/site-functions ${fpath})
 
 
-# tab completion handled by _j file
+# set error file location
+if [[ "$(uname)" == "Darwin" ]]; then
+    export AUTOJUMP_ERROR_PATH=~/Library/autojump/errors.log
+elif [[ -n "${XDG_DATA_HOME}" ]]; then
+    export AUTOJUMP_ERROR_PATH="${XDG_DATA_HOME}/autojump/errors.log"
+else
+    export AUTOJUMP_ERROR_PATH=~/.local/share/autojump/errors.log
+fi
 
 
 # change pwd hook
 autojump_chpwd() {
-    (autojump -a "$(pwd)" &) &>/dev/null
+    autojump --add "$(pwd)" >/dev/null 2>${AUTOJUMP_ERROR_PATH} &!
 }
 
 typeset -gaU chpwd_functions

From d4f824d79f38292bd8f0b3b7db32815dd7c1df00 Mon Sep 17 00:00:00 2001
From: William Ting <io@williamting.com>
Date: Tue, 7 Jan 2014 22:13:29 -0600
Subject: [PATCH 4/4] standardize to new age shell style

---
 bin/autojump.bash |  6 +++---
 bin/autojump.sh   |  2 +-
 bin/autojump.zsh  | 16 ++++++++--------
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/bin/autojump.bash b/bin/autojump.bash
index 6447900..88f7b21 100644
--- a/bin/autojump.bash
+++ b/bin/autojump.bash
@@ -1,5 +1,5 @@
 # set user installation paths
-if [ -d ~/.autojump/ ]; then
+if [[ -d ~/.autojump/ ]]; then
     export PATH=~/.autojump/bin:"${PATH}"
 fi
 
@@ -50,7 +50,7 @@ j() {
     fi
 
     new_path="$(autojump ${@})"
-    if [ -d "${new_path}" ]; then
+    if [[ -d "${new_path}" ]]; then
         echo -e "\\033[31m${new_path}\\033[0m"
         cd "${new_path}"
     else
@@ -79,7 +79,7 @@ jo() {
     fi
 
     new_path="$(autojump ${@})"
-    if [ -d "${new_path}" ]; then
+    if [[ -d "${new_path}" ]]; then
         case ${OSTYPE} in
             linux-gnu)
                 xdg-open "${new_path}"
diff --git a/bin/autojump.sh b/bin/autojump.sh
index 71bafd3..1d19202 100644
--- a/bin/autojump.sh
+++ b/bin/autojump.sh
@@ -1,6 +1,6 @@
 # source autojump on BASH or ZSH depending on the shell
 
-shell=`echo ${SHELL} | awk -F/ '{ print $NF }'`
+shell=$(echo ${SHELL} | awk -F/ '{ print $NF }')
 
 # prevent circular loop for sh shells
 if [ "${shell}" = "sh" ]; then
diff --git a/bin/autojump.zsh b/bin/autojump.zsh
index 80c09b4..a522bee 100644
--- a/bin/autojump.zsh
+++ b/bin/autojump.zsh
@@ -1,14 +1,14 @@
 # set user installation paths
-if [[ -d ${HOME}/.autojump ]]; then
-    path=(${HOME}/.autojump/bin ${path})
-    fpath=(${HOME}/.autojump/functions/ ${fpath})
+if [[ -d ~/.autojump ]]; then
+    path=(~/.autojump/bin ${path})
+    fpath=(~/.autojump/functions/ ${fpath})
 fi
 
 
 # set homebrew installation paths
-command -v brew &>/dev/null \
-    && [[ -d "`brew --prefix`/share/zsh/site-functions" ]] \
-    && fpath=(`brew --prefix`/share/zsh/site-functions ${fpath})
+if command -v brew && [[ -d "$(brew --prefix)/share/zsh/site-functions" ]]; then
+    fpath=("$(brew --prefix)/share/zsh/site-functions" ${fpath})
+fi
 
 
 # set error file location
@@ -38,7 +38,7 @@ j() {
     fi
 
     local new_path="$(autojump ${@})"
-    if [ -d "${new_path}" ]; then
+    if [[ -d "${new_path}" ]]; then
         echo -e "\\033[31m${new_path}\\033[0m"
         cd "${new_path}"
     else
@@ -67,7 +67,7 @@ jo() {
     fi
 
     local new_path="$(autojump ${@})"
-    if [ -d "${new_path}" ]; then
+    if [[ -d "${new_path}" ]]; then
         case ${OSTYPE} in
             linux-gnu)
                 xdg-open "${new_path}"