* 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
