[nongnu] elpa/better-jumper 3624896c72 05/48: add documentation

[ELPA Syncer]

branch: elpa/better-jumper
commit 3624896c72abc13ea08f47fb2e4b6905987a9e49
Author: Bryan Gilbert <gilbertw1@gmail.com>
Commit: Bryan Gilbert <gilbertw1@gmail.com>

    add documentation
---
 Readme.md        | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 better-jumper.el | 29 ++++++++++++--------
 2 files changed, 100 insertions(+), 12 deletions(-)

diff --git a/Readme.md b/Readme.md
index 4ab742a04a..cb95c373fb 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,3 +1,84 @@
 # better-jumper
 
-A configurable jump list implementation for Emacs
+A configurable jump list implementation for Emacs.
+
+<br />
+
+## Usage
+
+Better jumper exposes the following functions
+
+| Command                     | Description                                    
                     |
+|--------------------------   
|---------------------------------------------------------------------|
+| better-jumper-set-jump      | Adds a new jump location to jump list using 
current buffer/position |
+| better-jumper-jump-backward | Jumps to back to previous location in jump 
list                     |
+| better-jumper-jump-forward  | Jumps forward to next location in jump list    
                     |
+
+<br />
+
+## Configuration Options
+
+##### *Context* - `better-jumper-context`
+
+This setting specifies the context in which jump lists are tracked. This can
+either be set to `'buffer` or `'window`. If the value is `'buffer` then a jump
+list is maintained for each individual buffer. Conversly, if the value is
+`'window` then the jump list is maintained per window and will operate across
+buffers in that window.
+
+##### *Isolate Perspectives* - `better-jumper-isolate-perspectives`
+
+If this setting is non-nil then jump lists will be isolated between
+`persp-mode` perspectives. Additionally, jump list state will be saved 
alongside 
+perspective configuration when a perspective is saved.
+
+##### *New Window Behavior* - `better-jumper-new-window-behavior`
+
+This setting specifies the behavior that will take place when a new window is
+created AND the current context is set to `'window`. This can be either set to
+`'copy` or `'empty`. If the value is `'copy` then the last selected window's
+jump list will be copied to the new window. If the value is `'empty` then the
+new window's jump list will start empty.
+
+##### *Max Length* - `better-jumper-max-length`
+
+This is a numeric value that dictate the maximum length that a jump list can
+grow to. If the length of a jump list exceeds this size then the oldest items 
in
+the list will be dropped.
+
+##### *Use Evil Jump Advice* - `better-jumper-use-evil-jump-advice`
+
+If non-nil better jumper will attach a piece of advice to the `evil-jump`
+function that will ensure that anytime a jump is added using `evil-jump` a
+corresponding jump will be added using `better-jumper`.
+
+<br />
+
+## Hooks
+
+##### *Pre-jump Hook* - `better-jumper-pre-jump-hook`
+
+##### *Post-jump Hook* - `better-jumper-post-jump-hook`
+
+<br />
+
+## Comparison with `evil-jump`
+
+This package was heavily inspired by `evil-jump` and initially was planned as a
+modification of or pull request to `evil`. It was primarily born out of the
+desire to isolate jumps across `persp-mode` perspectives, however the changes
+proved to be to large to be a simple modification. Additionally, this package
+provides more customization options as well as a few other core improvements.
+
+A few advantages of `better-jumper` are:
+
+* Properly isolates jump lists between `persp-mode` perspectives and saves the
+  jump lists to those perspectives. It uses a number of tricks to accurately 
pin
+  jump lists to windows across perspectives.
+
+* True buffer specific jump lists. When instructed to not cross buffer
+  boundaries `evil-jumper` still tracks jumps per window only limits the jumps
+  available to ones located in the current buffer.
+  
+* Configurable new window behavior. `evil-jumper` ALWAYS copies the jump list
+  from the previously selected window to any newly created window.
diff --git a/better-jumper.el b/better-jumper.el
index 548185a238..859bf66e52 100644
--- a/better-jumper.el
+++ b/better-jumper.el
@@ -1,6 +1,7 @@
 ;;; better-jumper.el --- description -*- lexical-binding: t; -*-
 
 ;;; Commentary:
+;;;  A configurable jump list implementation for Emacs.
 ;;; Code:
 
 (defgroup better-jumper nil
@@ -30,6 +31,11 @@
   :type 'integer
   :group 'better-jumper)
 
+(defcustom better-jumper-use-evil-jump-advice t
+  "When non-nil, advice is added to add jumps whenever `evil-set-jump' is 
invoked."
+  :type 'boolean
+  :group 'better-jumper)
+
 (defcustom better-jumper-pre-jump-hook nil
   "Hooks to run just before jumping to a location in the jump list."
   :type 'hook
@@ -45,11 +51,6 @@
   :type '(repeat string)
   :group 'better-jumper)
 
-(defcustom better-jumper-use-evil-jump-advice t
-  "When non-nil, advice is added to add jumps whenever `evil-set-jump' is 
invoked."
-  :type 'boolean
-  :group 'better-jumper)
-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (defvar better-jumper--jumping nil
@@ -59,7 +60,7 @@
   "Regexp to match against `buffer-name' to determine whether it's a valid 
jump target.")
 
 (defvar better-jumper--jump-table (make-hash-table)
-  "Hashtable which stores all jumps on a per perspective/window basis.")
+  "Hashtable which stores all jumps on a per perspective/window/buffer basis.")
 
 (cl-defstruct better-jumper-jump-list-struct
   ring
@@ -255,6 +256,7 @@ Uses the current window or buffer if CONTEXT is nil."
 ;;;   PUBLIC FUNCTIONS    ;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+;;;###autoload
 (defun better-jumper-set-jump (&optional pos)
   "Set jump point at POS.
 POS defaults to point."
@@ -274,6 +276,7 @@ POS defaults to point."
         (goto-char pos))
       (better-jumper--push))))
 
+;;;###autoload
 (defun better-jumper-jump-backward ()
   "Jump backward to previous location in jump list."
   (interactive)
@@ -285,6 +288,7 @@ POS defaults to point."
       (better-jumper--push))
     (better-jumper--jump idx 1)))
 
+;;;###autoload
 (defun better-jumper-jump-forward ()
   "Jump forward to previous location in jump list."
   (interactive)
@@ -303,13 +307,15 @@ POS defaults to point."
 
 (defun better-jumper--before-persp-deactivate (&rest args)
   "Save jump state when a perspective is deactivated. Ignore ARGS."
-  (better-jumper--persp-disable-window-config-update)
-  (better-jumper--save-perspective-jump-state))
+  (when better-jumper-isolate-perspectives
+    (better-jumper--persp-disable-window-config-update)
+    (better-jumper--save-perspective-jump-state)))
 
 (defun better-jumper--on-persp-activate (&rest args)
   "Restore jump state when a perspective is activated. Ignore ARGS."
-  (better-jumper--restore-perspective-jump-state)
-  (better-jumper--persp-enable-window-config-update))
+  (when better-jumper-isolate-perspectives
+    (better-jumper--restore-perspective-jump-state)
+    (better-jumper--persp-enable-window-config-update)))
 
 (with-eval-after-load 'persp-mode
   (add-hook 'persp-before-deactivate-functions 
#'better-jumper--before-persp-deactivate)
@@ -323,7 +329,8 @@ Cleans up deleted windows and copies history to newly 
created windows."
     (let* ((window-list (window-list-1 nil nil t))
            (jump-table (better-jumper--get-jump-table)))
       (when (and (eq better-jumper-new-window-behavior 'copy)
-                 (not (better-jumper--persp-window-config-update-disabled)))
+                 (and better-jumper-isolate-perspectives
+                      (not 
(better-jumper--persp-window-config-update-disabled))))
         (let* ((curr-window (selected-window))
                (source-jump-struct (better-jumper--get-struct curr-window))
                (source-jump-list (better-jumper--get-struct-jump-list 
source-jump-struct)))