Cleanup and document the speed key feature

doc/ChangeLog

@@ -1,3 +1,7 @@
+2009-11-14  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Speed keys): New section.
+
 2009-11-08  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Agenda commands): Document the new `i' command.

doc/org.texi

@@ -394,6 +394,7 @@ Sample configuration
 Miscellaneous
 
 * Completion::                  M-TAB knows what you need
+* Speed keys::                  Electic commands at the beginning of a headline
 * Customization::               Adapting Org to your taste
 * In-buffer settings::          Overview of the #+KEYWORDS
 * The very busy C-c C-c key::   When in doubt, press C-c C-c
@@ -10323,6 +10324,7 @@ This may be necessary in particular if files include other files via
 
 @menu
 * Completion::                  M-TAB knows what you need
+* Speed keys::                  Electic commands at the beginning of a headline
 * Customization::               Adapting Org to your taste
 * In-buffer settings::          Overview of the #+KEYWORDS
 * The very busy C-c C-c key::   When in doubt, press C-c C-c
@@ -10332,7 +10334,7 @@ This may be necessary in particular if files include other files via
 @end menu
 
 
-@node Completion, Customization, Miscellaneous, Miscellaneous
+@node Completion, Speed keys, Miscellaneous, Miscellaneous
 @section Completion
 @cindex completion, of @TeX{} symbols
 @cindex completion, of TODO keywords
@@ -10394,7 +10396,25 @@ Elsewhere, complete dictionary words using Ispell.
 @end itemize
 @end table
 
-@node Customization, In-buffer settings, Completion, Miscellaneous
+@node Speed keys, Customization, Completion, Miscellaneous
+@section Speed keys
+@cindex speed keys
+@vindex org-use-speed-commands
+@vindex org-speed-commands-user
+
+Single keys can be made to execute commands when the cursor is at the
+beginning of a headline, i.e. before the first star.  Configure the variable
+@code{org-use-speed-commands} to activate this feature.  There is a
+pre-defined list of commands, and you can add more such commands using the
+variable @code{org-speed-commands-user}.  Speed keys do not only speed up
+navigation and other commands, but they also provide an alternative way to
+execute commands bound to keys that are not or not easily available on a tty,
+or on a small mobile device with a limited keyboard.
+
+To see which commands are available, activate the feature and press @kbd{?}
+with the cursor at the beginning of a headline.
+
+@node Customization, In-buffer settings, Speed keys, Miscellaneous
 @section Customization
 @cindex customization
 @cindex options, for customization
@@ -10836,26 +10856,26 @@ customized workaround suits you better.  For example, changing a timestamp
 is really only fun with @kbd{S-@key{cursor}} keys, whereas on a
 tty you would rather use @kbd{C-c .} to re-insert the timestamp.
 
-@multitable @columnfractions 0.15 0.2 0.2
-@item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
-@item @kbd{S-@key{TAB}}     @tab @kbd{C-u @key{TAB}}       @tab
-@item @kbd{M-@key{left}}    @tab @kbd{C-c C-x l}           @tab @kbd{@key{Esc} @key{left}}
-@item @kbd{M-S-@key{left}}  @tab @kbd{C-c C-x L}           @tab
-@item @kbd{M-@key{right}}   @tab @kbd{C-c C-x r}           @tab @kbd{@key{Esc} @key{right}}
-@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R}           @tab
-@item @kbd{M-@key{up}}      @tab @kbd{C-c C-x u}           @tab @kbd{@key{Esc} @key{up}}
-@item @kbd{M-S-@key{up}}    @tab @kbd{C-c C-x U}           @tab
-@item @kbd{M-@key{down}}    @tab @kbd{C-c C-x d}           @tab @kbd{@key{Esc} @key{down}}
-@item @kbd{M-S-@key{down}}  @tab @kbd{C-c C-x D}           @tab
-@item @kbd{S-@key{RET}}     @tab @kbd{C-c C-x c}           @tab
-@item @kbd{M-@key{RET}}     @tab @kbd{C-c C-x m}           @tab @kbd{@key{Esc} @key{RET}}
-@item @kbd{M-S-@key{RET}}   @tab @kbd{C-c C-x M}           @tab
-@item @kbd{S-@key{left}}    @tab @kbd{C-c @key{left}}      @tab
-@item @kbd{S-@key{right}}   @tab @kbd{C-c @key{right}}     @tab
-@item @kbd{S-@key{up}}      @tab @kbd{C-c @key{up}}        @tab
-@item @kbd{S-@key{down}}    @tab @kbd{C-c @key{down}}      @tab
-@item @kbd{C-S-@key{left}}  @tab @kbd{C-c C-x @key{left}}  @tab
-@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab
+@multitable @columnfractions 0.15 0.2 0.1 0.2
+@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} 
+@item @kbd{S-@key{TAB}}     @tab @kbd{C-u @key{TAB}}       @tab @kbd{C} @tab                            
+@item @kbd{M-@key{left}}    @tab @kbd{C-c C-x l}           @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} 
+@item @kbd{M-S-@key{left}}  @tab @kbd{C-c C-x L}           @tab @kbd{L} @tab                            
+@item @kbd{M-@key{right}}   @tab @kbd{C-c C-x r}           @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
+@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R}           @tab @kbd{R} @tab                           
+@item @kbd{M-@key{up}}      @tab @kbd{C-c C-x u}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}  
+@item @kbd{M-S-@key{up}}    @tab @kbd{C-c C-x U}           @tab @kbd{U} @tab                           
+@item @kbd{M-@key{down}}    @tab @kbd{C-c C-x d}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
+@item @kbd{M-S-@key{down}}  @tab @kbd{C-c C-x D}           @tab @kbd{D} @tab                            
+@item @kbd{S-@key{RET}}     @tab @kbd{C-c C-x c}           @tab @kbd{ } @tab
+@item @kbd{M-@key{RET}}     @tab @kbd{C-c C-x m}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
+@item @kbd{M-S-@key{RET}}   @tab @kbd{C-c C-x M}           @tab @kbd{ } @tab
+@item @kbd{S-@key{left}}    @tab @kbd{C-c @key{left}}      @tab @kbd{ } @tab
+@item @kbd{S-@key{right}}   @tab @kbd{C-c @key{right}}     @tab @kbd{ } @tab
+@item @kbd{S-@key{up}}      @tab @kbd{C-c @key{up}}        @tab @kbd{ } @tab
+@item @kbd{S-@key{down}}    @tab @kbd{C-c @key{down}}      @tab @kbd{ } @tab
+@item @kbd{C-S-@key{left}}  @tab @kbd{C-c C-x @key{left}}  @tab @kbd{ } @tab
+@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
 @end multitable
 
 

lisp/ChangeLog

@@ -1,3 +1,10 @@
+2009-11-14  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.el (org-speed-commands-user): Allow documentation headlines.
+	(org-speed-commands-default): Organize the value of this constant
+	with descriptive headlines.
+	(org-print-speed-command): Output the headlines.
+
 2009-11-13  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org-agenda.el (org-agenda-show-outline-path): New option.

lisp/org.el

@@ -611,14 +611,19 @@ and when the cursor is at the beginning of a headline.
 The car if each entry is a string with a single letter, which must
 be assigned to `self-insert-command' in the global map.
 The cdr is either a command to be called interactively, a function
-to be called, or a form to be evaluated."
+to be called, or a form to be evaluated.
+An entry that is just a list with a single string will be interpreted
+as a descriptive headline that will be added when listing the speed
+copmmands in the Help buffer using the `?' speed command."
     :group 'org-structure
-    :type '(repeat
-	    (cons
-	     (string "Command letter")
-	     (choice
-	      (function)
-	      (sexp)))))
+    :type '(repeat :value ("k" . ignore)
+	    (choice :value ("k" . ignore)
+	     (list :tag "Descriptive Headline" (string :tag "Headline"))
+	     (cons :tag "Letter and Command"
+	      (string :tag "Command letter")
+	      (choice
+	       (function)
+	       (sexp))))))
 
 (defgroup org-cycle nil
   "Options concerning visibility cycling in Org-mode."
@@ -14891,15 +14896,19 @@ Some of the options can be changed using the variable
 
 (defconst org-speed-commands-default
   '(
-    ("n" . org-speed-move-safe)
-    ("p" . org-speed-move-safe)
-    ("f" . org-speed-move-safe)
-    ("b" . org-speed-move-safe)
-    ("u" . org-speed-move-safe)
-    (" " . org-display-outline-path)
-
+    ("Outline Navigation")
+    ("n" . (org-speed-move-safe 'outline-next-visible-heading))
+    ("p" . (org-speed-move-safe 'outline-previous-visible-heading))
+    ("f" . (org-speed-move-safe 'org-forward-same-level))
+    ("b" . (org-speed-move-safe 'org-backward-same-level))
+    ("u" . (org-speed-move-safe 'outline-up-heading))
+    ("j" . org-goto)
+    ("g" . (org-refile t))
+    ("Outline Visibility")
     ("c" . org-cycle)
     ("C" . org-shifttab)
+    (" " . org-display-outline-path)
+    ("Outline Structure Editing")
     ("U" . org-shiftmetaup)
     ("D" . org-shiftmetadown)
     ("r" . org-metaright)
@@ -14908,37 +14917,45 @@ Some of the options can be changed using the variable
     ("L" . org-shiftmetaleft)
     ("i" . (progn (forward-char 1) (call-interactively
 				    'org-insert-heading-respect-content)))
-
-    ("v" . org-agenda)
-    ("/" . org-sparse-tree)
-    (";" . org-set-tags-command)
+    ("^" . org-sort)
+    ("w" . org-refile)
+    ("a" . org-archive-subtree-default-with-confirmation)
+    ("." . outline-mark-subtree)
+    ("Clock Commands")
     ("I" . org-clock-in)
     ("O" . org-clock-out)
-    ("o" . org-open-at-point)
+    ("Meta Data Editing")
     ("t" . org-todo)
-    ("j" . org-goto)
-    ("g" . (org-refile t))
-    ("e" . org-set-effort)
     ("0" . (org-priority ?\ ))
     ("1" . (org-priority ?A))
     ("2" . (org-priority ?B))
     ("3" . (org-priority ?C))
-    ("." . outline-mark-subtree)
-    ("^" . org-sort)
-    ("w" . org-refile)
-    ("a" . org-archive-subtree-default-with-confirmation)
+    (";" . org-set-tags-command)
+    ("e" . org-set-effort)
+    ("Agenda Views etc")
+    ("v" . org-agenda)
+    ("/" . org-sparse-tree)
     ("/" . org-sparse-tree)
+    ("Misc")
+    ("o" . org-open-at-point)
     ("?" . org-speed-command-help)
     )
   "The default speed commands.")
 
 (defun org-print-speed-command (e)
-  (princ (car e))
-  (princ "   ")
-  (if (symbolp (cdr e))
-      (princ (symbol-name (cdr e)))
-    (prin1 (cdr e)))
-  (princ "\n"))
+  (if (> (length (car e)) 1)
+      (progn
+	(princ "\n")
+	(princ (car e))
+	(princ "\n")
+	(princ (make-string (length (car e)) ?-))
+	(princ "\n"))
+    (princ (car e))
+    (princ "   ")
+    (if (symbolp (cdr e))
+	(princ (symbol-name (cdr e)))
+      (prin1 (cdr e)))
+    (princ "\n")))
 
 (defun org-speed-command-help ()
   "Show the available speed commands."
@@ -14946,23 +14963,23 @@ Some of the options can be changed using the variable
   (if (not org-use-speed-commands)
       (error "Speed commands are not activated, customize `org-use-speed-commands'.")
     (with-output-to-temp-buffer "*Help*"
-      (princ "Speed commands\n==============\n")
+      (princ "User-defined Speed commands\n===========================\n")
       (mapc 'org-print-speed-command org-speed-commands-user)
       (princ "\n")
-      (mapc 'org-print-speed-command org-speed-commands-default))))
-
-(defun org-speed-move-safe ()
+      (princ "Built-in Speed commands\n=======================\n")
+      (mapc 'org-print-speed-command org-speed-commands-default))
+    (with-current-buffer "*Help*"
+      (setq truncate-lines t))))
+
+(defun org-speed-move-safe (cmd)
+  "Execute CMD, but make sure that the cursor always ends up in a headline.
+If not, return to the original position and throw an error."
   (interactive)
-  (let ((pos (point))
-	(tbl '(("n" . outline-next-visible-heading)
-	       ("p" . outline-previous-visible-heading)
-	       ("f" . org-forward-same-level)
-	       ("b" . org-backward-same-level)
-	       ("u" . outline-up-heading))))
-    (call-interactively (cdr (assoc (this-command-keys) tbl)))
+  (let ((pos (point)))
+    (call-interactively cmd)
     (unless (and (bolp) (org-on-heading-p))
       (goto-char pos)
-      (error "Boundary reached"))))
+      (error "Boundary reached while executing %s" cmd))))
 
 (defvar org-self-insert-command-undo-counter 0)