Update documentation, particularly how to prefer symbolic links or change

directory weights within the database.
12 years ago · 2c2875f841
parent efa8bbcf81
commit 2c2875f841
5 changed files with 87 additions and 31 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@ -4,6 +4,8 @@

 Python v2.6+ or 3.0+

+Bash v4.0+ for tab completion
+
 ### AUTOMATIC INSTALLATION

 **Linux**
--- a/README.md
+++ b/README.md
@ -27,13 +27,10 @@ command line. The jumpstat command shows you the current contents of the
 database. Directories must be visited first before they can be jumped
 to.

-autojump supports tab completion in Bash v4.0+.
-
 OPTIONS
 -------

-Below options must be passed to 'autojump' and not the 'j' wrapper
-function.
+Options must be passed to 'autojump' and not the 'j' wrapper function.

    -a, --add DIR       manually add path to database

@ -44,30 +41,46 @@ function.
 INTERNAL OPTIONS
 ----------------

-    -b, --bash
+    -b, --bash          enclose directory with quotes to prevent errors

    --completion        prevent key weight decay over time

 ADVANCED USAGE
 --------------

-To manually change an entry's weight, edit the file
-$XDG\_DATA\_HOME/autojump/autojump.txt.
+-   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, export the following
+    configuration in your \~/.bashrc:
+
+        export AUTOJUMP_KEEP_SYMLINKS=1
+
+-   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:
+
+        29.3383211216   /home/user/downloads
+
+    All negative key weights are purged automatically.

 FILES
 -----

-If installed locally, autojump is self-contained in the directory
-\~/.autojump/.
+If installed locally, autojump is self-contained in *\~/.autojump/*.

-The database is stored in $XDG\_DATA\_HOME/autojump/autojump.txt.
+The database is stored in *$XDG\_DATA\_HOME/autojump/autojump.txt*.

 REPORTING BUGS
 --------------

 For any issues please visit the following URL:

-https://github.com/joelthelion/autojump/issues
+*https://github.com/joelthelion/autojump/issues*

 THANKS
 ------
@ -96,6 +109,8 @@ INSTALLATION

 Python v2.6+ or 3.0+

+Bash v4.0+ for tab completion
+
 ### AUTOMATIC INSTALLATION

 **Linux**
--- a/2
+++ b/2
@ -225,7 +225,7 @@ def shell_utility():
    parser.add_argument('-a', '--add', metavar='DIR', type=unicode,
            help='manually add path to database')
    parser.add_argument('-b', '--bash', action="store_true", default=False,
-            help='')
+            help='enclose directory quotes to prevent errors')
    parser.add_argument('--completion', action="store_true", default=False,
            help='prevent key weight decay over time')
    parser.add_argument('--stat', action="store_true", default=False,
--- a/autojump.1
+++ b/autojump.1
@ -26,12 +26,10 @@ It works by maintaining a database of the directories you use the most
 from the command line.
 The jumpstat command shows you the current contents of the database.
 Directories must be visited first before they can be jumped to.
-.PP
-autojump supports tab completion in Bash v4.0+.
 .SS OPTIONS
 .PP
-Below options must be passed to \[aq]autojump\[aq] and not the
-\[aq]j\[aq] wrapper function.
+Options must be passed to \[aq]autojump\[aq] and not the \[aq]j\[aq]
+wrapper function.
 .IP
 .nf
 \f[C]
@ -46,26 +44,57 @@ Below options must be passed to \[aq]autojump\[aq] and not the
 .IP
 .nf
 \f[C]
-b,\ --bash
+-b,\ --bash\ \ \ \ \ \ \ \ \ \ enclose\ directory\ with\ quotes\ to\ prevent\ errors

 --completion\ \ \ \ \ \ \ \ prevent\ key\ weight\ decay\ over\ time
 \f[]
 .fi
 .SS ADVANCED USAGE
+.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, export the following
+configuration in your ~/.bashrc:
+.IP
+.nf
+\f[C]
+export\ AUTOJUMP_KEEP_SYMLINKS=1
+\f[]
+.fi
+.RE
+.IP \[bu] 2
+Change Directory Weight
+.RS 2
+.PP
+To manually change a directory\[aq]s key weight, you can edit the file
+\f[I]$XDG_DATA_HOME/autojump/autojump.txt\f[].
+Each entry has two columns.
+The first is the key weight and the second is the path:
+.IP
+.nf
+\f[C]
+29.3383211216\ \ \ /home/user/downloads
+\f[]
+.fi
 .PP
-To manually change an entry\[aq]s weight, edit the file
-$XDG_DATA_HOME/autojump/autojump.txt.
+All negative key weights are purged automatically.
+.RE
 .SS FILES
 .PP
-If installed locally, autojump is self-contained in the directory
-~/.autojump/.
+If installed locally, autojump is self-contained in
+\f[I]~/.autojump/\f[].
 .PP
-The database is stored in $XDG_DATA_HOME/autojump/autojump.txt.
+The database is stored in \f[I]$XDG_DATA_HOME/autojump/autojump.txt\f[].
 .SS REPORTING BUGS
 .PP
 For any issues please visit the following URL:
 .PP
-https://github.com/joelthelion/autojump/issues
+\f[I]https://github.com/joelthelion/autojump/issues\f[]
 .SS THANKS
 .PP
 Special thanks goes out to: Pierre Gueth, Simon Marache-Francisco,
--- a/manpage.md
+++ b/manpage.md
@ -19,11 +19,9 @@ Show all database entries and their respective key weights:

 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. The jumpstat command shows you the current contents of the database. Directories must be visited first before they can be jumped to.

-autojump supports tab completion in Bash v4.0+.
-
 ## OPTIONS

-Below options must be passed to 'autojump' and not the 'j' wrapper function.
+Options must be passed to 'autojump' and not the 'j' wrapper function.

    -a, --add DIR       manually add path to database

@ -33,25 +31,37 @@ Below options must be passed to 'autojump' and not the 'j' wrapper function.

 ## INTERNAL OPTIONS

-    -b, --bash
+    -b, --bash          enclose directory with quotes to prevent errors

    --completion        prevent key weight decay over time

 ## ADVANCED USAGE

-To manually change an entry's weight, edit the file $XDG_DATA_HOME/autojump/autojump.txt.
+- 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, export the following configuration in your ~/.bashrc:
+
+        export AUTOJUMP_KEEP_SYMLINKS=1
+
+- 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:
+
+        29.3383211216   /home/user/downloads
+
+    All negative key weights are purged automatically.

 ## FILES

-If installed locally, autojump is self-contained in the directory ~/.autojump/.
+If installed locally, autojump is self-contained in _~/.autojump/_.

-The database is stored in $XDG_DATA_HOME/autojump/autojump.txt.
+The database is stored in _$XDG_DATA_HOME/autojump/autojump.txt_.

 ## REPORTING BUGS

 For any issues please visit the following URL:

-https://github.com/joelthelion/autojump/issues
+_https://github.com/joelthelion/autojump/issues_

 ## THANKS