Reorganize key bindings for archiving

The following keys now do archiving

C-c C-x C-a    archive using the command specified in
               `org-archive-default-command'

This variable is by default set to `org-archive-subtree', which means
arching to the archive file.

The three specific archiving commands are available through

C-c C-x C-s    archive to archive file
C-c C-x a      toggle the archive tag
C-c C-x A      move to archive sibling

These bindings work the same in an Org file, and in the agenda.

In addition:

- In the agenda you can also use `a' to call the default archiving
  command, but you need to confirm the command with `y' so that this
  cannot easily happen by accident.

- For backward compatibility, `C-c $' in an org-mode file, and `$' in
  the agenda buffer continue to archive to archive file.

doc/ChangeLog

@@ -1,3 +1,13 @@
+2009-10-31  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* orgcard.tex: Document the new archiving keys.
+
+	* org.texi (Archiving): Document the default archiving command.
+	(Moving subtrees): Documen the new keys for archiving.
+	(Internal archiving): Fix incorrect key.
+	(Agenda commands): Document the TODO set switching commands.
+	(Agenda commands): Document the new archiving keys.
+
 2009-10-24  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Clocking work time): Better description on how to save

doc/org.texi

@@ -6162,6 +6162,14 @@ to move the tree out of the way and to stop it from contributing to the
 agenda.  Archiving is important to keep your working files compact and global
 searches like the construction of agenda views fast.
 
+@table @kbd
+@kindex C-c C-x C-a
+@item C-c C-x C-a
+@vindex org-archive-default-command
+Archive the current entry using the command specified in the variable
+@code{org-archive-default-command}.
+@end table
+
 @menu
 * Moving subtrees::             Moving a tree to an archive file
 * Internal archiving::          Switch off a tree but keep i in the file
@@ -6177,8 +6185,7 @@ the archive file.
 @table @kbd
 @kindex C-c $
 @kindex C-c C-x C-s
-@itemx C-c $
-@item C-c C-x C-s
+@item C-c C-x C-s@ @r{or short} @ C-c $
 @vindex org-archive-location
 Archive the subtree starting at the cursor position to the location
 given by @code{org-archive-location}.
@@ -6250,7 +6257,7 @@ archived subtrees are not exposed, unless you configure the option
 During agenda view construction (@pxref{Agenda Views}), the content of
 archived trees is ignored unless you configure the option
 @code{org-agenda-skip-archived-trees}, in which case these trees will always
-be included.  In the agenda you can press the @kbd{v} key to get archives
+be included.  In the agenda you can press @kbd{v a} to get archives
 temporarily included.
 @item
 @vindex org-export-with-archived-trees
@@ -7380,6 +7387,7 @@ negative search term which @i{must not} occur/match in the entry for it to be
 selected.
 @end table
 
+@page
 @tsubheading{Remote editing}
 @cindex remote editing, from agenda
 
@@ -7398,6 +7406,11 @@ both in the agenda buffer and in the remote buffer.
 Change the TODO state of the item, both in the agenda and in the
 original org file.
 @c
+@kindex C-S-@key{right}
+@kindex C-S-@key{left}
+@item C-S-@key{right}@r{/}@key{left}
+Switch to the next/previous set of TODO keywords.
+@c
 @kindex C-k
 @item C-k
 @vindex org-agenda-confirm-kill
@@ -7410,17 +7423,26 @@ variable @code{org-agenda-confirm-kill}.
 @item C-c C-w
 Refile the entry at point.
 @c
+@kindex C-c C-x C-a
 @kindex a
-@item a
+@item C-c C-x C-a @ @r{or short} @ a
+@vindex org-archive-default-command
+Archive the subtree corresponding to the entry at point using the default
+archiving command set in @code{org-archive-default-command}.  When using the
+@code{a} key, confirmation will be required.
+@c
+@kindex C-c C-x a
+@item C-c C-x a
 Toggle the ARCHIVE tag for the current headline.
 @c
-@kindex A
-@item A
+@kindex C-c C-x A
+@item C-c C-x A
 Move the subtree corresponding to the current entry to its @emph{archive
 sibling}.
 @c
 @kindex $
-@item $
+@kindex C-c C-x C-s
+@item C-c C-x C-s @ @r{or short} @ $
 Archive the subtree corresponding to the current headline.  This means the
 entry will be moved to the configured archive location, most likely a
 different file.

doc/orgcard.tex

@@ -322,27 +322,17 @@ are preserved on all copies.
 
 \section{Archiving}
 
-\key{toggle ARCHIVE tag}{C-c C-x a}
-\key{force cycling of an ARCHIVEd tree}{C-TAB}
-\key{move to Attic Sibling}{C-c C-x A}
-%\metax{mark fully done children}{C-u C-c C-x C-a}
+\key{archive subtree using the default command}{C-c C-x C-a}
 \key{move subtree to archive file}{C-c C-x C-s}
-%\metax{move all fully done children}{C-u C-c C-x C-s}
-%To set archive location for current file, add a line like$^2$:
-%\vskip -1mm
-%\beginexample%
-%\#+ARCHIVE: archfile::* Archived Tasks
-%\endexample
+\key{toggle ARCHIVE tag / to ARCHIVE sibling}{C-c C-x a/A}
+\key{force cycling of an ARCHIVEd tree}{C-TAB}
 
 \section{Filtering and Sparse Trees}
 
-% FIXME: this is garbage
 \key{construct a sparse tree by various criteria}{C-c /}
 \key{view TODO's in sparse tree}{C-c C-v}
 \key{global TODO list in agenda mode}{C-c a t$^1$}
 \key{time sorted view of current org file}{C-c a L}
-%\key{agenda for the week}{C-c a$^1$}
-%\key{agenda for date at cursor}{C-c C-o}
 
 \section{Tables}
 
@@ -649,7 +639,7 @@ after  ``{\tt :}'', and dictionary words elsewhere.
 \key{digit argument}{0-9}
 \key{change state of current TODO item}{t}
 \key{kill item and source}{C-k}
-\key{archive the subtree (file/tag/sibling)}{\$ / a / A}
+\key{archive default}{\$ / a}
 \key{refile the subtree}{C-c C-w}
 \key{set/show tags of current headline}{: / T}
 \key{set effort property (prefix=nth)}{e}

lisp/ChangeLog

@@ -1,5 +1,21 @@
 2009-10-31  Carsten Dominik  <carsten.dominik@gmail.com>
 
+	* org.el (org-mode-map): Define the new archiving keys.
+	(org-speed-commands-default): Define an archiving key in the speed
+	command map.
+	(org-org-menu): Improve the menu structure concerning archiving.
+
+	* org-archive.el (org-archive-subtree-default-with-confirmation):
+	New command.
+
+	* org-agenda.el (org-agenda-mode-map): Define the new archiving keys.
+	(org-agenda-menu): Add the new archiving commands to the menu.
+	(org-agenda-archive-default)
+	(org-agenda-archive-default-with-confirmation): New commands.
+	(org-agenda-archive, org-agenda-archive-to-archive-sibling): Just
+	call `org-agenda-archive-with'.
+	(org-agenda-archive-with): New function.
+
 	* org-table.el (org-table-convert-region): Inert spaces around "|"
 	to avoid line beginnings like "|-1" which will be mistaken as
 	hlines.

lisp/org-agenda.el

@@ -1389,10 +1389,12 @@ The following commands are available:
 (org-defkey org-agenda-mode-map "U"        'org-agenda-bulk-remove-all-marks)
 (org-defkey org-agenda-mode-map "B"        'org-agenda-bulk-action)
 (org-defkey org-agenda-mode-map "\C-c\C-x!" 'org-reload)
-(org-defkey org-agenda-mode-map "\C-c$"    'org-agenda-archive)
+(org-defkey org-agenda-mode-map "\C-c\C-x\C-a" 'org-agenda-archive-default)
+(org-defkey org-agenda-mode-map "\C-c\C-xa"    'org-agenda-toggle-archive-tag)
+(org-defkey org-agenda-mode-map "\C-c\C-xA"    'org-agenda-archive-to-archive-sibling)
 (org-defkey org-agenda-mode-map "\C-c\C-x\C-s" 'org-agenda-archive)
+(org-defkey org-agenda-mode-map "\C-c$"        'org-agenda-archive)
 (org-defkey org-agenda-mode-map "$"        'org-agenda-archive)
-(org-defkey org-agenda-mode-map "A"        'org-agenda-archive-to-archive-sibling)
 (org-defkey org-agenda-mode-map "\C-c\C-o" 'org-agenda-open-link)
 (org-defkey org-agenda-mode-map " "        'org-agenda-show-and-scroll-up)
 (org-defkey org-agenda-mode-map [backspace] 'org-agenda-show-scroll-down)
@@ -1404,7 +1406,7 @@ The following commands are available:
 (org-defkey org-agenda-mode-map "L"        'org-agenda-recenter)
 (org-defkey org-agenda-mode-map "\C-c\C-t" 'org-agenda-todo)
 (org-defkey org-agenda-mode-map "t"        'org-agenda-todo)
-(org-defkey org-agenda-mode-map "a"        'org-agenda-toggle-archive-tag)
+(org-defkey org-agenda-mode-map "a"        'org-agenda-archive-default-with-confirmation)
 (org-defkey org-agenda-mode-map ":"        'org-agenda-set-tags)
 (org-defkey org-agenda-mode-map "\C-c\C-q" 'org-agenda-set-tags)
 (org-defkey org-agenda-mode-map "."        'org-agenda-goto-today)
@@ -1577,6 +1579,8 @@ The following commands are available:
      ["Previous TODO set" org-agenda-todo-previousset t]
      ["Add note" org-agenda-add-note t])
     ("Archive/Refile/Delete"
+     ["Archive default" org-agenda-archive-default t]
+     ["Archive default" org-agenda-archive-default-with-confirmation t]
      ["Toggle ARCHIVE tag" org-agenda-toggle-archive-tag t]
      ["Move to archive sibling" org-agenda-archive-to-archive-sibling t]
      ["Archive subtree" org-agenda-archive t]
@@ -5756,25 +5760,29 @@ Point is in the buffer where the item originated.")
      (with-current-buffer buffer (delete-region dbeg dend))
      (message "Agenda item and source killed"))))
 
+(defun org-agenda-archive-default ()
+  "Archive the entry or subtree belonging to the current agenda entry."
+  (interactive)
+  (require 'org-archive)
+  (org-agenda-archive-with org-archive-default-command))
+
+(defun org-agenda-archive-default-with-confirmation ()
+  "Archive the entry or subtree belonging to the current agenda entry."
+  (interactive)
+  (require 'org-archive)
+  (org-agenda-archive-with org-archive-default-command 'confirm))
+
 (defun org-agenda-archive ()
   "Archive the entry or subtree belonging to the current agenda entry."
   (interactive)
-  (or (eq major-mode 'org-agenda-mode) (error "Not in agenda"))
-  (let* ((marker (or (org-get-at-bol 'org-marker)
-		     (org-agenda-error)))
-	 (buffer (marker-buffer marker))
-	 (pos (marker-position marker)))
-    (org-with-remote-undo buffer
-      (with-current-buffer buffer
-	(if (org-mode-p)
-	    (save-excursion
-	      (goto-char pos)
-	      (org-remove-subtree-entries-from-agenda)
-	      (org-back-to-heading t)
-	      (org-archive-subtree))
-	  (error "Archiving works only in Org-mode files"))))))
+  (org-agenda-archive-with 'org-archive-subtree))
 
 (defun org-agenda-archive-to-archive-sibling ()
+  "Move the entry to the archive sibling."
+  (interactive)
+  (org-agenda-archive-with 'org-archive-to-archive-sibling))
+
+(defun org-agenda-archive-with (cmd &optional confirm)
   "Move the entry to the archive sibling."
   (interactive)
   (or (eq major-mode 'org-agenda-mode) (error "Not in agenda"))
@@ -5785,11 +5793,14 @@ Point is in the buffer where the item originated.")
     (org-with-remote-undo buffer
       (with-current-buffer buffer
 	(if (org-mode-p)
-	    (save-excursion
-	      (goto-char pos)
-	      (org-remove-subtree-entries-from-agenda)
-	      (org-back-to-heading t)
-	      (org-archive-to-archive-sibling))
+	    (if (and confirm
+		     (not (y-or-n-p "Archive this subtree or entry? ")))
+		(error "Abort")
+	      (save-excursion
+		(goto-char pos)
+		(org-remove-subtree-entries-from-agenda)
+		(org-back-to-heading t)
+		(funcall cmd)))
 	  (error "Archiving works only in Org-mode files"))))))
 
 (defun org-remove-subtree-entries-from-agenda (&optional buf beg end)

lisp/org-archive.el

@@ -35,8 +35,7 @@
 (declare-function org-inlinetask-remove-END-maybe "org-inlinetask" ())
 
 (defcustom org-archive-default-command 'org-archive-subtree
-  "The default archiving command.
-Currently this is only used by org-mobile.el."
+  "The default archiving command."
   :group 'org-archive
   :type '(choice
 	  (const org-archive-subtree)
@@ -444,6 +443,14 @@ This command is set with the variable `org-archive-default-command'."
   (interactive)
   (call-interactively org-archive-default-command))
 
+(defun org-archive-subtree-default-with-confirmation ()
+  "Archive the current subtree with the default command.
+This command is set with the variable `org-archive-default-command'."
+  (interactive)
+  (if (y-or-n-p "Archive this subtree or entry? ")
+      (call-interactively org-archive-default-command)
+    (error "Abort")))
+
 (provide 'org-archive)
 
 ;; arch-tag: 0837f601-9699-43c3-8b90-631572ae6c85

lisp/org.el

@@ -14523,7 +14523,7 @@ Some of the options can be changed using the variable
 (org-defkey org-mode-map "\C-c\C-b"    'org-backward-same-level)
 (org-defkey org-mode-map "\C-c$"    'org-archive-subtree)
 (org-defkey org-mode-map "\C-c\C-x\C-s" 'org-advertized-archive-subtree)
-(org-defkey org-mode-map "\C-c\C-x\C-a" 'org-toggle-archive-tag)
+(org-defkey org-mode-map "\C-c\C-x\C-a" 'org-archive-subtree-default)
 (org-defkey org-mode-map "\C-c\C-xa" 'org-toggle-archive-tag)
 (org-defkey org-mode-map "\C-c\C-xA" 'org-archive-to-archive-sibling)
 (org-defkey org-mode-map "\C-c\C-xb" 'org-tree-to-indirect-buffer)
@@ -14656,6 +14656,7 @@ Some of the options can be changed using the variable
     ("." . outline-mark-subtree)
     ("^" . org-sort)
     ("w" . org-refile)
+    ("a" . org-archive-subtree-default-with-confirmation)
     ("/" . org-sparse-tree)
     ("?" . org-speed-command-help)
     )
@@ -15638,21 +15639,11 @@ See the individual commands for more information."
      ["Footnote new/jump" org-footnote-action t]
      ["Footnote extra" (org-footnote-action t) :active t :keys "C-u C-c C-x f"])
     ("Archive"
-     ["Toggle ARCHIVE tag" org-toggle-archive-tag t]
-;     ["Check and Tag Children" (org-toggle-archive-tag (4))
-;      :active t :keys "C-u C-c C-x C-a"]
-     ["Sparse trees open ARCHIVE trees"
-      (setq org-sparse-tree-open-archived-trees
-	    (not org-sparse-tree-open-archived-trees))
-      :style toggle :selected org-sparse-tree-open-archived-trees]
-     ["Cycling opens ARCHIVE trees"
-      (setq org-cycle-open-archived-trees (not org-cycle-open-archived-trees))
-      :style toggle :selected org-cycle-open-archived-trees]
+     ["Archive (default method)" org-archive-subtree-default t]
      "--"
-     ["Move subtree to archive sibling" org-archive-to-archive-sibling t]
-     ["Move Subtree to Archive" org-advertized-archive-subtree t]
- ;    ["Check and Move Children" (org-archive-subtree '(4))
- ;     :active t :keys "C-u C-c C-x C-s"]
+     ["Move Subtree to Archive file" org-advertized-archive-subtree t]
+     ["Toggle ARCHIVE tag" org-toggle-archive-tag t]
+     ["Move subtree to Archive sibling" org-archive-to-archive-sibling t]
      )
     "--"
     ("Hyperlinks"