Sorting: Improve documentation, and implement better time sorting

Sorting entries by time is now much more flexible, and can be
specified to creation, scheduled, and deadline time.

doc/ChangeLog

@@ -1,3 +1,10 @@
+2009-05-06  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* orgcard.tex: Document the key for sorting.
+
+	* org.texi (Structure editing, Plain lists): Improve documentation
+	on sorting.
+
 2009-04-17  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Internal links): Document custom ids for links.

doc/org.texi

@@ -1026,12 +1026,13 @@ Refile entry or region to a different location.  @xref{Refiling notes}.
 Sort same-level entries.  When there is an active region, all entries in the
 region will be sorted.  Otherwise the children of the current headline are
 sorted.  The command prompts for the sorting method, which can be
-alphabetically, numerically, by time (using the first time stamp in each
-entry), by priority, or by TODO keyword (in the sequence the keywords have
-been defined in the setup).  Reverse sorting is possible as well.  You can
-also supply your own function to extract the sorting key.  With a @kbd{C-u}
-prefix, sorting will be case-sensitive.  With two @kbd{C-u C-u} prefixes,
-duplicate entries will also be removed.
+alphabetically, numerically, by time (first time stamp with active preferred,
+creation time, scheduled time, deadline time), by priority, by TODO keyword
+(in the sequence the keywords have been defined in the setup) or by the value
+of a property.  Reverse sorting is possible as well.  You can also supply
+your own function to extract the sorting key.  With a @kbd{C-u} prefix,
+sorting will be case-sensitive.  With two @kbd{C-u C-u} prefixes, duplicate
+entries will also be removed.
 @kindex C-x n s
 @item C-x n s
 Narrow buffer to current subtree.
@@ -1413,6 +1414,10 @@ converted into a list item.
 This command also cycles bullet styles when the cursor in on the bullet or
 anywhere in an item line, details depending on
 @code{org-support-shift-select}.
+@kindex C-c ^
+@item C-c ^
+Sort the plain list.  You will be prompted for the sorting method:
+numerically, alphabetically, by time, or by custom function.
 @end table
 
 @node Drawers, Footnotes, Plain lists, Document Structure

doc/orgcard.tex

@@ -283,7 +283,6 @@ are preserved on all copies.
 (define-key global-map "\\C-ca" 'org-agenda)$^1$
 \endexample
 %
-\metax{For the many customization options try}{M-x org-customize}
 \metax{To read the on-line documentation try}{M-x org-info}
 
 \section{Visibility Cycling}
@@ -314,6 +313,7 @@ are preserved on all copies.
 \metax{promote/demote current subtree}{M-S-LEFT/RIGHT}
 
 \metax{move subtree/list item up/down}{M-S-UP/DOWN}
+\metax{sort subtree/region/plain-list}{C-c \^{}}
 \metax{clone a subtree}{C-c C-x c}
 \metax{refile subtree}{C-c C-w}
 \metax{kill/copy subtree}{C-c C-x C-w/M-w}

lisp/ChangeLog

@@ -1,3 +1,8 @@
+2009-05-06  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.el (org-sort-entries-or-items): Improve docstring, and make
+	better implementation for time sorting.
+
 2009-05-05  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.el (org-edit-src-persistent-message): New option.

lisp/org.el

@@ -6084,15 +6084,35 @@ With a double prefix argument, also remove duplicate entries."
 
 (defun org-sort-entries-or-items
   (&optional with-case sorting-type getkey-func compare-func property)
-  "Sort entries on a certain level of an outline tree.
+  "Sort entries on a certain level of an outline tree, or plain list items.
 If there is an active region, the entries in the region are sorted.
 Else, if the cursor is before the first entry, sort the top-level items.
 Else, the children of the entry at point are sorted.
+If the cursor is at the first item in a plain list, the list items will be
+sorted.
+
+Sorting can be alphabetically, numerically, by date/time as given by
+a time stamp, by a property or by priority.
+
+The command prompts for the sorting type unless it has been given to the
+function through the SORTING-TYPE argument, which needs to a character,
+\(?n ?N ?a ?A ?t ?T ?s ?S ?d ?D ?p ?P ?r ?R ?f ?F).  Here is the
+precise meaning of each character:
+
+n   Numerically, by converting the beginning of the entry/item to a number.
+a   Alphabetically, ignoring the TODO keyword and the priority, if any.
+t   By date/time, either the first active time stamp in the entry, or, if
+    none exist, by the first inactive one.
+    In items, only the first line will be chekced.
+s   By the scheduled date/time.
+d   By deadline date/time.
+c   By creation time, which is assumed to be the first inactive time stamp
+    at the beginning of a line.
+p   By priority according to the cookie.
+r   By the value of a property.
+
+Capital letters will reverse the sort order.
 
-Sorting can be alphabetically, numerically, and by date/time as given by
-the first time stamp in the entry.  The command prompts for the sorting
-type unless it has been given to the function through the SORTING-TYPE
-argument, which needs to a character, any of (?n ?N ?a ?A ?t ?T ?p ?P ?f ?F).
 If the SORTING-TYPE is ?f or ?F, then GETKEY-FUNC specifies a function to be
 called with point at the beginning of the record.  It must return either
 a string or a number that should serve as the sorting key for that record.
@@ -6155,8 +6175,10 @@ WITH-CASE, the sorting considers case as well."
     (unless sorting-type
       (message
        (if plain-list-p
-	   "Sort %s: [a]lpha [n]umeric [t]ime [f]unc  A/N/T/F means reversed:"
-	 "Sort %s: [a]lpha [n]umeric [t]ime [p]riority p[r]operty todo[o]rder [f]unc  A/N/T/P/O/F means reversed:")
+	   "Sort %s: [a]lpha  [n]umeric  [t]ime  [f]unc   A/N/T/F means reversed:"
+	 "Sort %s: [a]lpha  [n]umeric  [p]riority  p[r]operty  todo[o]rder  [f]unc
+               [t]ime [s ]cheduled  [d]eadline  [c]reated
+               A/N/T/S/D/C/P/O/F means reversed:")
        what)
       (setq sorting-type (read-char-exclusive))
 
@@ -6213,10 +6235,12 @@ WITH-CASE, the sorting considers case as well."
 		  ((= dcst ?a)
 		   (buffer-substring (match-end 0) (point-at-eol)))
 		  ((= dcst ?t)
-		   (if (re-search-forward org-ts-regexp
-					  (point-at-eol) t)
-		       (org-time-string-to-time (match-string 0))
-		     now))
+		   (if (or (re-search-forward org-ts-regexp (point-at-eol) t)
+			   (re-search-forward org-ts-regexp-both
+					      (point-at-eol) t))
+		       (time-to-seconds
+			(org-time-string-to-time (match-string 0)))
+		     (time-to-seconds now)))
 		  ((= dcst ?f)
 		   (if getkey-func
 		       (progn
@@ -6236,12 +6260,29 @@ WITH-CASE, the sorting considers case as well."
 		   (funcall case-func (match-string 4))
 		 nil))
 	      ((= dcst ?t)
-	       (if (re-search-forward org-ts-regexp
-				      (save-excursion
-					(forward-line 2)
-					(point)) t)
-		   (org-time-string-to-time (match-string 0))
-		 now))
+	       (let ((end (save-excursion (outline-next-heading) (point))))
+		 (if (or (re-search-forward org-ts-regexp end t)
+			 (re-search-forward org-ts-regexp-both end t))
+		     (org-time-string-to-time (match-string 0))
+		   (org-time-string-to-time now))))
+	      ((= dcst ?c)
+	       (let ((end (save-excursion (outline-next-heading) (point))))
+		 (if (re-search-forward
+		      (concat "^[ \t]*\\[" org-ts-regexp1 "\\]")
+		      end t)
+		     (time-to-seconds (org-time-string-to-time
+				       (match-string 0)))
+		   (time-to-seconds now))))
+	      ((= dcst ?s)
+	       (let ((end (save-excursion (outline-next-heading) (point))))
+		 (if (re-search-forward org-scheduled-time-regexp end t)
+		     (org-time-string-to-time (match-string 1))
+		   (org-time-string-to-time now))))
+	      ((= dcst ?d)
+	       (let ((end (save-excursion (outline-next-heading) (point))))
+		 (if (re-search-forward org-deadline-time-regexp end t)
+		     (org-time-string-to-time (match-string 1))
+		   (org-time-string-to-time now))))
 	      ((= dcst ?p)
 	       (if (re-search-forward org-priority-regexp (point-at-eol) t)
 		   (string-to-char (match-string 2))