From ad7f0fb27ec1a2077d63e2a94c2a3909b54aa549 Mon Sep 17 00:00:00 2001 From: William Ting Date: Fri, 1 Feb 2013 14:45:47 -0600 Subject: [PATCH] update docs --- README.md | 82 ++++++++++++++----------------- docs/autojump.1 | 117 +++++++++++++++++++++++--------------------- docs/body.md | 111 +++++++++++++++++++++-------------------- docs/development.md | 6 ++- docs/install.md | 2 +- 5 files changed, 162 insertions(+), 156 deletions(-) diff --git a/README.md b/README.md index 85252ff..207788a 100644 --- a/README.md +++ b/README.md @@ -138,12 +138,46 @@ Options must be passed to 'autojump' and not the 'j' wrapper function. --version show version information and exit -INTERNAL OPTIONS ----------------- +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. - -b, --bash enclose directory with quotes to prevent errors + jc images + +- Open File Manager To Directories (instead of jumping) - --complete used for tab completion + 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 + +- ZSH Tab Completion + + Tab completion requires two tabs before autojump will display the + completion menu. However if `setopt nolistambiguous` is enabled, + then only one tab is required. ADDITIONAL CONFIGURATION ------------------------ @@ -193,46 +227,6 @@ ADDITIONAL CONFIGURATION Changes require reloading autojump to take into effect. - -ADVANCED USAGE --------------- - -- 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 - -- 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 - - 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 jump - you into /home/user/work/inbox. - -- ZSH Tab Completion - - Tab completion requires two tabs before autojump will display the - completion menu. However if `setopt nolistambiguous` is enabled, - then only one tab is required. - - Change Directory Weight To manually change a directory's key weight, you can edit the file diff --git a/docs/autojump.1 b/docs/autojump.1 index 5042457..c5b0ea5 100644 --- a/docs/autojump.1 +++ b/docs/autojump.1 @@ -52,15 +52,72 @@ wrapper function. --version\ \ \ \ \ \ \ \ \ \ \ show\ version\ information\ and\ exit \f[] .fi -.SS INTERNAL OPTIONS +.SS ADVANCED USAGE +.IP \[bu] 2 +Using Multiple Arguments +.RS 2 +.PP +Let\[aq]s assume the following database: .IP .nf \f[C] --b,\ --bash\ \ \ \ \ \ \ \ \ \ enclose\ directory\ with\ quotes\ to\ prevent\ errors - ---complete\ \ \ \ \ \ \ \ \ \ used\ for\ tab\ completion +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 +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 +name. +.IP +.nf +\f[C] +jc\ images +\f[] +.fi +.RE +.IP \[bu] 2 +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. +.IP +.nf +\f[C] +jo\ music \f[] .fi +.PP +Opening a file manager to a child directory is also supported. +.IP +.nf +\f[C] +jco\ images +\f[] +.fi +.RE +.IP \[bu] 2 +ZSH Tab Completion +.RS 2 +.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. +.RE .SS ADDITIONAL CONFIGURATION .IP \[bu] 2 Enable ZSH Tab Completion @@ -141,58 +198,6 @@ export\ AUTOJUMP_AUTOCOMPLETE_CMDS=\[aq]cp\ vim\[aq] Changes require reloading autojump to take into effect. .RE .IP \[bu] 2 -Use a File Manager to Open Jumped-to Directories -.RS 2 -.PP -You can modify your ~/.bashrc or ~/.zsh to make autojump open a -directory for you. -Add the following lines in your ~/.bashrc or ~/.zshrc: -.IP -.nf -\f[C] -function\ jo\ {\ xdg-open\ $(autojump\ $\@);\ } -complete\ -F\ _autojump\ jo -\f[] -.fi -.PP -If you\[aq]re using Mac OS X, you can replace \f[C]xdg-open\f[] with -\f[C]open\f[]. -.PP -After executing \f[C]source\ ~/.bashrc\f[] or \f[C]source\ ~/.zshrc\f[], -you can try \f[C]jo\ foo\f[], which behaves like \f[C]j\ foo\f[] except -that it opens the \f[C]foo\f[] directory with a file manager. -.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 -ZSH Tab Completion -.RS 2 -.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. -.RE -.IP \[bu] 2 Change Directory Weight .RS 2 .PP diff --git a/docs/body.md b/docs/body.md index 79b5827..f32b893 100644 --- a/docs/body.md +++ b/docs/body.md @@ -10,93 +10,98 @@ Options must be passed to 'autojump' and not the 'j' wrapper function. --version show version information and exit -## INTERNAL OPTIONS +ADVANCED USAGE +-------------- - -b, --bash enclose directory with quotes to prevent errors +- Using Multiple Arguments - --complete used for tab completion + Let's assume the following database: -## ADDITIONAL CONFIGURATION + 30 /home/user/mail/inbox + 10 /home/user/work/inbox -- Enable ZSH Tab Completion + `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. - ZSH tab completion requires the `compinit` module to be loaded. Please add - the following line to your ~/.zshrc: +- Jump to a Child Directory. - autoload -U compinit; compinit + Sometimes it's convenient to jump to a child directory (sub-directory of + current directory) rather than typing out the full name. -- Always Ignore Case + jc images - 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: +- Open File Manager To Directories (instead of jumping) - export AUTOJUMP_IGNORE_CASE=1 + Instead of jumping to a directory, you can open a file explorer window (Mac + Finder, Windows Explorer, GNOME Nautilus, etc) to the directory instead. -- Prevent Database Entries' Decay + jo music - Default behavior is to decay unused database entries slowly over time. - Eventually when database limits are hit and maintenance is run, autojump - will purge older less used entries. To prevent decay, add the following - variable in your ~/.bashrc: + Opening a file manager to a child directory is also supported. - export AUTOJUMP_KEEP_ALL_ENTRIES=1 + jco images -- Prefer Symbolic Links +- ZSH Tab Completion - 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: + Tab completion requires two tabs before autojump will display the + completion menu. However if `setopt nolistambiguous` is enabled, + then only one tab is required. - export AUTOJUMP_KEEP_SYMLINKS=1 +ADDITIONAL CONFIGURATION +------------------------ -- Autocomplete Additional Commands (Bash only) +- Enable ZSH Tab Completion - 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: + ZSH tab completion requires the `compinit` module to be loaded. + Please add the following line to your \~/.zshrc: - export AUTOJUMP_AUTOCOMPLETE_CMDS='cp vim' + autoload -U compinit; compinit - Changes require reloading autojump to take into effect. +- Always Ignore Case -- Use a File Manager to Open Jumped-to Directories + 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: - You can modify your ~/.bashrc or ~/.zsh to make autojump open a directory for you. Add the following lines in your ~/.bashrc or ~/.zshrc: + export AUTOJUMP_IGNORE_CASE=1 - function jo { xdg-open $(autojump $@); } - complete -F _autojump jo +- Prevent Database Entries' Decay - If you're using Mac OS X, you can replace `xdg-open` with `open`. + Default behavior is to decay unused database entries slowly over + time. Eventually when database limits are hit and maintenance is + run, autojump will purge older less used entries. To prevent decay, + add the following variable in your \~/.bashrc: - After executing `source ~/.bashrc` or `source ~/.zshrc`, you can try `jo foo`, which behaves like `j foo` except that it opens the `foo` directory with a file manager. + export AUTOJUMP_KEEP_ALL_ENTRIES=1 -## ADVANCED USAGE +- Prefer Symbolic Links -- Using Multiple Arguments + 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: - Let's assume the following database: + export AUTOJUMP_KEEP_SYMLINKS=1 - 30 /home/user/mail/inbox - 10 /home/user/work/inbox +- Autocomplete Additional Commands (Bash only) - `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. + 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: -- ZSH Tab Completion + export AUTOJUMP_AUTOCOMPLETE_CMDS='cp vim' - Tab completion requires two tabs before autojump will display the completion - menu. However if `setopt nolistambiguous` is enabled, then only one tab is - required. + Changes require reloading autojump to take into effect. -- Change Directory Weight +- 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: + *$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 diff --git a/docs/development.md b/docs/development.md index 6ec808f..626554d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,8 +1,10 @@ ## DEVELOPMENT -The source code is primarily in `./bin/autojump`. Various shell wrapper scripts are also available in `./bin/`. +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: +Documentation is in various files under `./docs/`. Build documentation with the +command: make docs diff --git a/docs/install.md b/docs/install.md index 594a93d..b22d96b 100644 --- a/docs/install.md +++ b/docs/install.md @@ -50,7 +50,7 @@ Grab a copy of autojump: Run the installation script: cd autojump - ./install.sh [ --local ] [ --zsh ] + ./install.sh [ --local ] and follow on screen instructions.