Update sort / goto rationale

Use "open" comment, fallback to "gd" for "open at point"

Split the concept of "go to defition" in the rationale.
This yields distinct sections:

- Go to definition
- Go to current entity
- Open thing at point
- Emacs-style jumping

10 files changed, 64 insertions, 44 deletions

diff --git a/evil-arc-mode.el b/evil-arc-mode.el
index 89456a9..832d9bb 100644
--- a/evil-arc-mode.el
+++ b/evil-arc-mode.el
@@ -45,10 +45,12 @@
     "gg" 'beginning-of-buffer
     "G" 'end-of-buffer
 
-    ;; goto
-    (kbd "<return>") 'archive-view
-    "o" 'archive-extract
-    "O" 'archive-extract-other-window
+    ;; open
+    (kbd "<return>") 'archive-extract
+    (kbd "S-<return>") 'archive-extract-other-window
+    (kbd "M-<return>") 'archive-view
+    "gd" 'archive-extract
+    "gD" 'archive-extract-other-window
 
     "a" 'archive-alternate-display
     "d" 'archive-flag-deleted
diff --git a/evil-calendar.el b/evil-calendar.el
index 1320fc6..b82c349 100644
--- a/evil-calendar.el
+++ b/evil-calendar.el
@@ -67,7 +67,7 @@
     ;; goto
     "." 'calendar-goto-today
     "gd" 'calendar-goto-date ; "gd" in evil-org-agenda, "gd" in Emacs.
-    ;; "gd" 'calendar-other-month ; Not very useful if we have `calendar-goto-date'.
+    ;; "gD" 'calendar-other-month ; Not very useful if we have `calendar-goto-date'.
 
     ;; diary
     "D" 'diary-view-other-diary-entries
diff --git a/evil-dired.el b/evil-dired.el
index 753adf3..26f0b88 100644
--- a/evil-dired.el
+++ b/evil-dired.el
@@ -129,11 +129,12 @@
     "x" 'dired-do-flagged-delete
     "y" 'dired-show-file-type
     "+" 'dired-create-directory
-    ;; goto
-    "o" 'dired-find-file-other-window
-    (kbd "C-o") 'dired-display-file
+    ;; open
+    (kbd "S-<return>") 'dired-find-file-other-window
+    (kbd "M-<return>") 'dired-display-file
+    "gD" 'dired-find-file-other-window
     ;; sort
-    "s" 'dired-sort-toggle-or-edit
+    "o" 'dired-sort-toggle-or-edit
     ;; moving
     "<" 'dired-prev-dirline
     ">" 'dired-next-dirline
diff --git a/evil-info.el b/evil-info.el
index f56a488..1ce6716 100644
--- a/evil-info.el
+++ b/evil-info.el
@@ -52,7 +52,7 @@
     ;; TODO: Should search with "n"/"N" cover the full manual like "C-s"/"C-r" does?
 
     ;; goto
-    "gd" 'Info-goto-node
+    "gd" 'Info-goto-node ; TODO: "gd" does not match the rationale of "go to definition". Change?
     "gt" 'Info-top-node
     "gT" 'Info-toc
     "gf" 'Info-follow-reference
diff --git a/evil-man.el b/evil-man.el
index e7684b6..d235a20 100644
--- a/evil-man.el
+++ b/evil-man.el
@@ -48,8 +48,8 @@
 
     ;; goto
     "gm" 'man
-    "gd" 'Man-goto-section
-    "gR" 'Man-follow-manual-reference
+    "gd" 'Man-goto-section ; TODO: "gd" does not match the rationale of "go to definition". Change?
+    "gR" 'Man-follow-manual-reference ; TODO: Make this match Info-follow-reference?
     "gs" 'Man-goto-see-also-section
 
     ;; refresh
diff --git a/evil-occur.el b/evil-occur.el
index fd103d0..5d8ebb9 100644
--- a/evil-occur.el
+++ b/evil-occur.el
@@ -43,10 +43,12 @@
     [mouse-2] 'occur-mode-mouse-goto
     (kbd "C-c C-c") 'occur-mode-goto-occurrence
 
-    ;; goto
-    (kbd "C-m") 'occur-mode-goto-occurrence
-    "o" 'occur-mode-goto-occurrence-other-window
-    (kbd "C-o") 'occur-mode-display-occurrence
+    ;; open
+    (kbd "<return>") 'occur-mode-goto-occurrence
+    (kbd "S-<return>") 'occur-mode-goto-occurrence-other-window
+    (kbd "M-<return>") 'occur-mode-display-occurrence
+    "gd" 'occur-mode-goto-occurrence
+    "gD" 'occur-mode-goto-occurrence-other-window
 
     "gj" 'occur-next
     "gk" 'occur-prev
diff --git a/evil-pdf.el b/evil-pdf.el
index 9cf9d6d..7779ff9 100644
--- a/evil-pdf.el
+++ b/evil-pdf.el
@@ -132,11 +132,14 @@
 
   (evil-set-initial-state 'pdf-outline-buffer-mode 'motion)
   (evil-define-key 'motion pdf-outline-buffer-mode-map
-    (kbd "<return>") 'pdf-outline-follow-link
-    (kbd "M-<return>") 'pdf-outline-follow-link-and-quit
-    (kbd "SPC") 'pdf-outline-display-link
+    ;; open
+    (kbd "<return>") 'pdf-outline-follow-link-and-quit
+    (kbd "S-<return>") 'pdf-outline-follow-link
+    (kbd "M-<return>") 'pdf-outline-display-link
+    "gd" 'pdf-outline-follow-link-and-quit
+    "gD" 'pdf-outline-follow-link
     "." 'pdf-outline-move-to-current-page
-    "o" 'pdf-outline-select-pdf-window
+    (kbd "SPC") 'pdf-outline-select-pdf-window
 
     "G" 'pdf-outline-end-of-buffer
     "^" 'pdf-outline-up-heading
@@ -151,17 +154,19 @@
     "ZZ" 'pdf-outline-quit-and-kill)
 
   (evil-define-key 'motion pdf-occur-buffer-mode-map
-    ;; goto
+    ;; open
     (kbd "<return>") 'pdf-occur-goto-occurrence
-    (kbd "o") 'pdf-occur-view-occurrence
-    (kbd "C-o") 'pdf-occur-view-occurrence ; TODO: "o" is probably a better binding.
+    (kbd "S-<return>") 'pdf-occur-view-occurrence
     (kbd "SPC") 'pdf-occur-view-occurrence
+    "gd" 'pdf-occur-goto-occurrence
+    "gD" 'pdf-occur-view-occurrence
 
     "A" 'pdf-occur-tablist-gather-documents
     "D" 'pdf-occur-tablist-do-delete
 
     ;; sort
-    "S" 'tabulated-list-sort
+    "o" 'tabulated-list-sort
+    "O" 'tablist-sort ; TODO: Do we need this?
 
     ;; refresh
     "G" 'tablist-revert
@@ -185,7 +190,6 @@
     ;; "f" 'tablist-find-entry ; TODO: Equivalent to 'pdf-occur-goto-occurrence?
     "r" 'pdf-occur-revert-buffer-with-args
     "d" 'tablist-do-kill-lines
-    "s" 'tablist-sort
     "x" 'pdf-occur-tablist-do-flagged-delete
     (kbd "<delete>") 'tablist-unmark-backward
     (kbd "S-SPC") 'scroll-down-command
diff --git a/evil-profiler.el b/evil-profiler.el
index 5729049..a4ff3bc 100644
--- a/evil-profiler.el
+++ b/evil-profiler.el
@@ -43,7 +43,6 @@
     "k" 'profiler-report-previous-entry
 
     (kbd "<tab>") 'profiler-report-toggle-entry
-    (kbd "<return>") 'profiler-report-toggle-entry
     "i" 'profiler-report-toggle-entry
 
     ;; sort
@@ -55,7 +54,8 @@
     "i" 'profiler-report-describe-entry
     "=" 'profiler-report-compare-profile
 
-    ;; goto
+    ;; open
+    (kbd "<return>") 'profiler-report-find-entry
     "gd" 'profiler-report-find-entry
 
     ;; refresh
diff --git a/evil-transmission.el b/evil-transmission.el
index a40739d..a8dd373 100644
--- a/evil-transmission.el
+++ b/evil-transmission.el
@@ -41,7 +41,7 @@
     (kbd "<delete>") 'scroll-down-command
 
     ;; sort
-    "s" 'tabulated-list-sort
+    "o" 'tabulated-list-sort
 
     (kbd "<return>") 'transmission-files
     "p" 'transmission-peers
@@ -79,7 +79,7 @@
     (kbd "<delete>") 'scroll-down-command
 
     ;; sort
-    "s" 'tabulated-list-sort
+    "o" 'tabulated-list-sort
 
     "p" 'transmission-peers
     "i" 'transmission-info
@@ -89,11 +89,14 @@
     "U" 'transmission-files-want
     "P" 'transmission-files-priority
 
-    ;; goto
+    ;; open
     (kbd "<return>") 'transmission-find-file
-    (kbd "S-<return>") 'transmission-display-file
-    "o" 'transmission-find-file-other-window
-    "O" 'transmission-view-file
+    (kbd "S-<return>") 'transmission-find-file-other-window
+    (kbd "M-<return>") 'transmission-display-file
+    "gd" 'transmission-find-file
+    "gD" 'transmission-find-file-other-window
+
+    "v" 'transmission-view-file
 
     "!" 'transmission-files-command
     ;; "X" 'transmission-files-command
@@ -129,7 +132,7 @@
   (evil-set-initial-state 'transmission-peers-mode 'motion)
   (evil-define-key 'motion transmission-peers-mode-map
     ;; sort
-    "s" 'tabulated-list-sort
+    "o" 'tabulated-list-sort
 
     "i" 'transmission-info
 
diff --git a/readme.org b/readme.org
index 99debe2..fc5656e 100644
--- a/readme.org
+++ b/readme.org
@@ -258,25 +258,33 @@ region, making this binding useless.
 
 [[http://www.nongnu.org/ranger/][ranger]] uses ~o~, inspired from [[http://mutt.org][Mutt]].
 
-*** Jumping / go to definition / view, display other window (~gd~, ~.~, ~o~, ~O~, ~RET~, ~S-RET~, ~M-RET~)
+*** Go to definition (~gd~, ~gD~)
 
-- ~gd~: [g]o to [d]efinition.  Unless ~RET~ has an obvious meaning, it should be a synonym of ~gd~.
+- ~gd~: [g]o to [d]efinition.  This is mostly for programming modes.
   If there's a corresponding 'pop' action, use ~C-t~.
 
-- ~o~, ~O~: go to definition in other window and display in other window respectively.
+*** Go to current entity
+
+- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
+  Bind only if more relevant than ~evil-repeat~.
+
+*** Open thing at point (~RET~, ~S-RET~, ~M-RET~, ~gd~, ~gD~)
+
+- ~RET~, ~S-RET~, ~M-RET~: Open thing at point in current window, open in other window and display in other window respectively.
   The latter is like the former with the focus remaining on the current window.
 
-- ~S-RET~, ~M-RET~: Same as ~o~ and ~O~ when available.
+- ~gd~, ~gD~: When available, same as ~RET~ and ~S-RET~ respectively.  This is
+  useful in terminals where ~S-RET~ might not work.
 
-The point of having two binding pairs is that they might not always be available.
+*** Emacs-style jumping (~J~)
 
-- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
-  Bind only if more relevant than ~evil-repeat~.
+- ~J~: [[mu4e][mu4e]] has ~j~ and [[evil-mu4e][evil-mu4e]] uses ~J~, so we use ~J~ too.
 
-Existing bindings:
+Some special modes like [[mu4e][mu4e]] and ibuffer offer to to "jump" to a different
+buffer.  This sometimes depends on the thing at point.
 
-- mu4e has ~j~ in Emacs, ~J~ in Evil.
-- ~C-o~ is possibly used for "display other window".
+This is not related to Evil jumps like ~C-i~ and ~C-o~, nor to "go to
+definition".
 
 *** Browse URL (~gx~)