diff --git a/doc/ChangeLog b/doc/ChangeLog index 5bc33e7f6..1e20c5e28 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,10 @@ +2009-05-06 Carsten Dominik + + * orgcard.tex: Document the key for sorting. + + * org.texi (Structure editing, Plain lists): Improve documentation + on sorting. + 2009-04-17 Carsten Dominik * org.texi (Internal links): Document custom ids for links. diff --git a/doc/org.texi b/doc/org.texi index 87747e6fc..139eda788 100644 --- a/doc/org.texi +++ b/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 diff --git a/doc/orgcard.tex b/doc/orgcard.tex index bd0d281fc..73ee2c279 100644 --- a/doc/orgcard.tex +++ b/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} diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 7acbcc192..961e60f94 100755 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2009-05-06 Carsten Dominik + + * org.el (org-sort-entries-or-items): Improve docstring, and make + better implementation for time sorting. + 2009-05-05 Carsten Dominik * org.el (org-edit-src-persistent-message): New option. diff --git a/lisp/org.el b/lisp/org.el index 7f00d3476..588edb2be 100644 --- a/lisp/org.el +++ b/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))