From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jan Malakhovski Subject: [PATCH 3/4] simplify and document `org-effort-durations'-related code Date: Sun, 27 Dec 2015 15:13:48 +0000 Message-ID: <1451229229-18973-4-git-send-email-oxij@oxij.org> References: <1451229229-18973-1-git-send-email-oxij@oxij.org> Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:60750) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aDD1R-00055I-Sz for emacs-orgmode@gnu.org; Sun, 27 Dec 2015 10:14:17 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aDD1Q-0004Gv-2t for emacs-orgmode@gnu.org; Sun, 27 Dec 2015 10:14:13 -0500 Received: from fujibayashi-1-pt.tunnel.tserv10.par1.ipv6.he.net ([2001:470:1f12:446::2]:46217 helo=tricoro.koumakan.jp) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aDD1P-0004Go-Nr for emacs-orgmode@gnu.org; Sun, 27 Dec 2015 10:14:12 -0500 In-Reply-To: <1451229229-18973-1-git-send-email-oxij@oxij.org> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Cc: Jan Malakhovski * lisp/org.el (org-time-clocksum-use-effort-durations): Make obsolete. (org-effort-durations-default): (org-effort-durations-8h): (org-effort-durations-6h): New constants. (org-effort-durations): Redefine and document. (org-minutes-to-clocksum-string): Simplify. * lisp/org-agenda.el: (org-agenda-show-clocking-issues): (org-agenda-format-item): Use new constants. * lisp/org.el: * lisp/org-clock.el: * lisp/org-colview.el: Document everything related to (org-effort-durations) a bit better. --- lisp/org-agenda.el | 4 +- lisp/org-clock.el | 5 ++- lisp/org-colview.el | 1 + lisp/org.el | 118 ++++++++++++++++++++++++++++++++-------------------- 4 files changed, 79 insertions(+), 49 deletions(-) diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 99ccedd..d8f9a96 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -5922,7 +5922,7 @@ please use `org-class' instead." "Add overlays, showing issues with clocking. See also the user option `org-agenda-clock-consistency-checks'." (interactive) - (let* ((org-time-clocksum-use-effort-durations nil) + (let* ((org-effort-durations org-effort-durations-default) (pl org-agenda-clock-consistency-checks) (re (concat "^[ \t]*" org-clock-string @@ -6550,7 +6550,7 @@ Any match of REMOVE-RE will be removed from TXT." (if s2 (setq s2 (org-get-time-of-day s2 'string t))) ;; Try to set s2 if s1 and `org-agenda-default-appointment-duration' are set - (let (org-time-clocksum-use-effort-durations) + (let (org-effort-durations org-effort-durations-default) (when (and s1 (not s2) org-agenda-default-appointment-duration) (setq s2 (org-minutes-to-clocksum-string diff --git a/lisp/org-clock.el b/lisp/org-clock.el index b7a70dc..df993b0 100644 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -724,8 +724,8 @@ previous clocking intervals." VALUE can be a number of minutes, or a string with format hh:mm or mm. When the string starts with a + or a - sign, the current value of the effort property will be changed by that amount. If the effort value is expressed -as an `org-effort-durations' (e.g. \"3h\"), the modified value will be -converted to a hh:mm duration. +using modifiers (e.g. \"3h\", see `org-clocksum-string-to-minutes'), the +modified value will be converted to a hh:mm duration. This command will update the \"Effort\" property of the currently clocked item, and the value displayed in the mode line." @@ -2468,6 +2468,7 @@ from the dynamic block definition." (maxlevel (or (plist-get params :maxlevel) 3)) (emph (plist-get params :emphasize)) (level-p (plist-get params :level)) + ;; FIXME: setting this will break `org-clock-time%' (org-time-clocksum-use-effort-durations (plist-get params :effort-durations)) (timestamp (plist-get params :timestamp)) diff --git a/lisp/org-colview.el b/lisp/org-colview.el index a3ce406..f6ad85e 100644 --- a/lisp/org-colview.el +++ b/lisp/org-colview.el @@ -1107,6 +1107,7 @@ display, or in the #+COLUMNS line of the current buffer." ((memq fmt '(checkbox checkbox-n-of-m checkbox-percent)) (if (equal s "[X]") 1. 0.000001)) ((memq fmt '(estimate)) (org-string-to-estimate s)) + ;; FIXME: this is ugly ((string-match (concat "\\([0-9.]+\\) *\\(" (regexp-opt (mapcar 'car org-effort-durations)) "\\)") s) diff --git a/lisp/org.el b/lisp/org.el index 24f81e4..e3f6bb6 100755 --- a/lisp/org.el +++ b/lisp/org.el @@ -3145,8 +3145,13 @@ commands, if custom time display is turned on at the time of export." (defcustom org-time-clocksum-format '(:days "%dd " :hours "%d" :require-hours t :minutes ":%02d" :require-minutes t) - "The format string used when creating CLOCKSUM lines. -This is also used when Org mode generates a time duration. + "The format string used when creating CLOCKSUM lines and time +durations (see `org-minutes-to-clocksum-string'). + +Note, that setting this to something that +`org-clocksum-string-to-minutes' can not parse and invert will +confuse time computations that go through text representation +phase (e.g. time percent computations in clock reports/tables). The value can be a single format string containing two %-sequences, which will be filled with the number of hours and @@ -3156,8 +3161,9 @@ Alternatively, the value can be a plist associating any of the keys :years, :months, :weeks, :days, :hours or :minutes with format strings. The time duration is formatted using only the time components that are needed and concatenating the results. -If a time unit in absent, it falls back to the next smallest -unit. +If a time unit (modifier) in absent, it falls back to the next +smallest modifier. The length of each modifier is defined by +`org-effort-durations'. The keys :require-years, :require-months, :require-days, :require-weeks, :require-hours, :require-minutes are also @@ -3168,7 +3174,7 @@ its value is 0. For example, - (:days \"%dd\" :hours \"%d\" :require-hours t :minutes \":%02d\" + (:days \"%dd \" :hours \"%d\" :require-hours t :minutes \":%02d\" :require-minutes t) means durations longer than a day will be expressed in days, @@ -3178,7 +3184,7 @@ hour). The value - (:days \"%dd\" :minutes \"%dm\") + (:days \"%dd \" :minutes \"%dmin\") means durations longer than a day will be expressed in days and minutes, and durations less than a day will be expressed entirely @@ -3220,6 +3226,10 @@ in minutes (even for durations longer than an hour)." (const :tag "Always show minutes" :require-minutes) (const t))))) +(make-obsolete-variable + 'org-time-clocksum-use-effort-durations + "Set `org-effort-durations' directly instead." "Org mode version 8.3") + (defcustom org-time-clocksum-use-fractional nil "When non-nil, \\[org-clock-display] uses fractional times. See `org-time-clocksum-format' for more on time clock formats." @@ -3228,20 +3238,6 @@ See `org-time-clocksum-format' for more on time clock formats." :version "24.3" :type 'boolean) -(defcustom org-time-clocksum-use-effort-durations nil - "When non-nil, \\[org-clock-display] uses effort durations. -E.g. by default, one day is considered to be a 8 hours effort, -so a task that has been clocked for 16 hours will be displayed -as during 2 days in the clock display or in the clocktable. - -See `org-effort-durations' on how to set effort durations -and `org-time-clocksum-format' for more on time clock formats." - :group 'org-time - :group 'org-clock - :version "24.4" - :package-version '(Org . "8.0") - :type 'boolean) - (defcustom org-time-clocksum-fractional-format "%.2f" "The format string used when creating CLOCKSUM lines, or when Org mode generates a time duration, if @@ -18169,48 +18165,80 @@ If there is already a time stamp at the cursor position, update it." (org-insert-time-stamp (encode-time 0 0 0 (nth 1 cal-date) (car cal-date) (nth 2 cal-date)))))) -(defcustom org-effort-durations +(defconst org-effort-durations-default + `(("min" . 1) + ("h" . 60) + ("d" . ,(* 60 24)) + ("w" . ,(* 60 24 7)) + ("m" . ,(* 60 24 30)) + ("y" . ,(* 60 24 365))) + "The conventional '24-hours-a-day, 7-days-a-week, 30-days-a-month, 365-days-a-year' definition of `org-effort-durations'.") + +(defconst org-effort-durations-8h `(("min" . 1) ("h" . 60) ("d" . ,(* 60 8)) ("w" . ,(* 60 8 5)) ("m" . ,(* 60 8 5 4)) ("y" . ,(* 60 8 5 40))) - "Conversion factor to minutes for an effort modifier. + "The '8-hours-a-day, 5-days-a-week, 4-weeks-a-month, 40-weeks-a-year' definition of `org-effort-durations'.") + +(defconst org-effort-durations-6h + `(("min" . 1) + ("h" . 60) + ("d" . ,(* 60 6)) + ("w" . ,(* 60 6 5)) + ("m" . ,(* 60 6 5 4)) + ("y" . ,(* 60 6 5 40))) + "The '6-hours-a-day, 5-days-a-week, 4-weeks-a-month, 40-weeks-a-year' definition of `org-effort-durations'.") + +(defcustom org-effort-durations + org-effort-durations-default + "Conversion factor to minutes for an effort unit (modifier) +used by `org-minutes-to-clocksum-string' and +`org-clocksum-string-to-minutes'. Each entry has the form (MODIFIER . MINUTES). In an effort string, a number followed by MODIFIER is multiplied -by the specified number of MINUTES to obtain an effort in -minutes. +by the specified number of MINUTES to obtain an effort in minutes +and vice versa. -For example, if the value of this variable is ((\"hours\" . 60)), then an -effort string \"2hours\" is equivalent to 120 minutes." +This variable is required to define at least 'h', 'd', 'w', 'm', +and 'y' modifiers since they are referenced in the definition of +`org-minutes-to-clocksum-string'. The latter function ignores +other modifiers, but `org-clocksum-string-to-minutes' uses them +all when possible. + +The default value is `org-effort-durations-default', but there +are also handy commonly used `org-effort-durations-8h' and +`org-effort-durations-6h'." :group 'org-agenda + :group 'org-time + :group 'org-clock :version "25.1" :package-version '(Org . "8.3") - :type '(alist :key-type (string :tag "Modifier") - :value-type (number :tag "Minutes"))) + :type `(choice (const :tag "24-hours-a-day, 7-days-a-week, 30-days-a-month, 365-days-a-year" ,org-effort-durations-default) + (const :tag "8-hours-a-day, 5-days-a-week, 4-weeks-a-month, 40-weeks-a-year" ,org-effort-durations-8h) + (const :tag "6-hours-a-day, 5-days-a-week, 4-weeks-a-month, 40-weeks-a-year" ,org-effort-durations-6h) + (alist :tag "Custom" + :key-type (string :tag "Modifier") + :value-type (number :tag "Minutes")))) (defun org-minutes-to-clocksum-string (m) "Format number of minutes as a clocksum string. The format is determined by `org-time-clocksum-format', +`org-effort-durations', `org-time-clocksum-use-fractional' and -`org-time-clocksum-fractional-format' and -`org-time-clocksum-use-effort-durations'." - (let ((clocksum "") - (m (round m)) ; Don't allow fractions of minutes - h d w mo y fmt n) - (setq h (if org-time-clocksum-use-effort-durations - (cdr (assoc "h" org-effort-durations)) 60) - d (if org-time-clocksum-use-effort-durations - (/ (cdr (assoc "d" org-effort-durations)) h) 24) - w (if org-time-clocksum-use-effort-durations - (/ (cdr (assoc "w" org-effort-durations)) (* d h)) 7) - mo (if org-time-clocksum-use-effort-durations - (/ (cdr (assoc "m" org-effort-durations)) (* d h)) 30) - y (if org-time-clocksum-use-effort-durations - (/ (cdr (assoc "y" org-effort-durations)) (* d h)) 365)) +`org-time-clocksum-fractional-format'." + (let* ((clocksum "") + (m (round m)) ; Don't allow fractions of minutes + (h (cdr (assoc "h" org-effort-durations))) + (d (/ (cdr (assoc "d" org-effort-durations)) h)) + (w (/ (cdr (assoc "w" org-effort-durations)) (* d h))) + (mo (/ (cdr (assoc "m" org-effort-durations)) (* d h))) + (y (/ (cdr (assoc "y" org-effort-durations)) (* d h))) + fmt n) ;; fractional format (if org-time-clocksum-use-fractional (cond @@ -18306,8 +18334,8 @@ If no number is found, the return value is 0." (defun org-clocksum-string-to-minutes (s &optional output-to-string) "Convert a duration string S to minutes. -A bare number is interpreted as minutes, modifiers can be set by -customizing `org-effort-durations' (which see). +A bare number is interpreted as minutes, units (modifiers) can be +set by customizing `org-effort-durations' (which see). Entries containing a colon are interpreted as H:MM by `org-hh:mm-string-to-minutes'." -- 2.6.4