emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Format of Effort estimates should be mentioned in its Info node
@ 2020-01-02 19:14 Kisaragi Hiu
  2020-01-04  2:55 ` Kyle Meyer
  2020-02-01  9:24 ` Bastien
  0 siblings, 2 replies; 9+ messages in thread
From: Kisaragi Hiu @ 2020-01-02 19:14 UTC (permalink / raw)
  To: emacs-orgmode

Currently, the Info node about effort estimates does not mention what
format should it be written in. This causes confusion, as a user might
assume that it's the same format as schedulers (10m, 6h, etc.) like I
did.

Simply mentioning "Effort estimates need to have the format H:MM"
(copied from the docstring or org-effort-property, the only*
description of the format I could find) in the Info node would be
enough.


*: searching for regexp effort.*format and manually filtering out the other 3 matches

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-02 19:14 Format of Effort estimates should be mentioned in its Info node Kisaragi Hiu
@ 2020-01-04  2:55 ` Kyle Meyer
  2020-01-04  5:20   ` Kisaragi Hiu
  2020-02-01  9:24 ` Bastien
  1 sibling, 1 reply; 9+ messages in thread
From: Kyle Meyer @ 2020-01-04  2:55 UTC (permalink / raw)
  To: Kisaragi Hiu, emacs-orgmode

Kisaragi Hiu <mail@kisaragi-hiu.com> writes:

> Currently, the Info node about effort estimates does not mention what
> format should it be written in. This causes confusion, as a user might
> assume that it's the same format as schedulers (10m, 6h, etc.) like I
> did.
>
> Simply mentioning "Effort estimates need to have the format H:MM"

I don't personally use effort estimates, but quickly poking around I see
some indication that estimates should work fine with things like 10min
rather than 0:10.  In particular org-set-effort has a bit that looks
like this:

  (org-refresh-property '((effort . identity)
                          (effort-minutes . org-duration-to-minutes))
                        value)

The presence of org-duration-to-minutes hints to some sort of
normalization:

  (org-duration-to-minutes "10min") ; => 10.0
  (org-duration-to-minutes "0:10")  ; => 10.0

And it looks like org-agenda-compare-effort uses the effort-minutes text
property.  That's presumably why, when I view the entries below in the
agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:

  * TODO a
    :PROPERTIES:
    :Effort:  10min
    :END:

  * TODO b
    :PROPERTIES:
    :Effort:   0:10
    :END:

But that's just one use of effort values, and it sounds like you've hit
into cases where the 10min form didn't work as expected.  Could you
provide more details?

> (copied from the docstring or org-effort-property, the only*
> description of the format I could find) in the Info node would be
> enough.

Given the above, it seems like org-effort-property's docstring is at
least somewhat inaccurate.

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-04  2:55 ` Kyle Meyer
@ 2020-01-04  5:20   ` Kisaragi Hiu
  2020-01-04  5:29     ` Jean-Christophe Helary
  0 siblings, 1 reply; 9+ messages in thread
From: Kisaragi Hiu @ 2020-01-04  5:20 UTC (permalink / raw)
  To: Kyle Meyer, Emacs Orgmode

It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.

Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.

2020年1月4日 11:55 差出し人: kyle@kyleam.com:

> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>
>> Currently, the Info node about effort estimates does not mention what
>> format should it be written in. This causes confusion, as a user might
>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>> did.
>>
>> Simply mentioning "Effort estimates need to have the format H:MM"
>>
>
> I don't personally use effort estimates, but quickly poking around I see
> some indication that estimates should work fine with things like 10min
> rather than 0:10.  In particular org-set-effort has a bit that looks
> like this:
>
> (org-refresh-property '((effort . identity)
> (effort-minutes . org-duration-to-minutes))
> value)
>
> The presence of org-duration-to-minutes hints to some sort of
> normalization:
>
> (org-duration-to-minutes "10min") ; => 10.0
> (org-duration-to-minutes "0:10")  ; => 10.0
>
> And it looks like org-agenda-compare-effort uses the effort-minutes text
> property.  That's presumably why, when I view the entries below in the
> agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:
>
> * TODO a
> :PROPERTIES:
> :Effort:  10min
> :END:
>
> * TODO b
> :PROPERTIES:
> :Effort:   0:10
> :END:
>
> But that's just one use of effort values, and it sounds like you've hit
> into cases where the 10min form didn't work as expected.  Could you
> provide more details?
>
>> (copied from the docstring or org-effort-property, the only*
>> description of the format I could find) in the Info node would be
>> enough.
>>
>
> Given the above, it seems like org-effort-property's docstring is at
> least somewhat inaccurate.
>

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-04  5:20   ` Kisaragi Hiu
@ 2020-01-04  5:29     ` Jean-Christophe Helary
  2020-01-07  8:41       ` Nicolas Goaziou
  0 siblings, 1 reply; 9+ messages in thread
From: Jean-Christophe Helary @ 2020-01-04  5:29 UTC (permalink / raw)
  To: Emacs Orgmode



> On Jan 4, 2020, at 14:20, Kisaragi Hiu <mail@kisaragi-hiu.com> wrote:
> 
> It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.
> 
> Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.

This does look like a potential contribution to the package.

Jean-Christophe Helary

> 
> 2020年1月4日 11:55 差出し人: kyle@kyleam.com:
> 
>> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>> 
>>> Currently, the Info node about effort estimates does not mention what
>>> format should it be written in. This causes confusion, as a user might
>>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>>> did.
>>> 
>>> Simply mentioning "Effort estimates need to have the format H:MM"
>>> 
>> 
>> I don't personally use effort estimates, but quickly poking around I see
>> some indication that estimates should work fine with things like 10min
>> rather than 0:10.  In particular org-set-effort has a bit that looks
>> like this:
>> 
>> (org-refresh-property '((effort . identity)
>> (effort-minutes . org-duration-to-minutes))
>> value)
>> 
>> The presence of org-duration-to-minutes hints to some sort of
>> normalization:
>> 
>> (org-duration-to-minutes "10min") ; => 10.0
>> (org-duration-to-minutes "0:10")  ; => 10.0
>> 
>> And it looks like org-agenda-compare-effort uses the effort-minutes text
>> property.  That's presumably why, when I view the entries below in the
>> agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:
>> 
>> * TODO a
>> :PROPERTIES:
>> :Effort:  10min
>> :END:
>> 
>> * TODO b
>> :PROPERTIES:
>> :Effort:   0:10
>> :END:
>> 
>> But that's just one use of effort values, and it sounds like you've hit
>> into cases where the 10min form didn't work as expected.  Could you
>> provide more details?
>> 
>>> (copied from the docstring or org-effort-property, the only*
>>> description of the format I could find) in the Info node would be
>>> enough.
>>> 
>> 
>> Given the above, it seems like org-effort-property's docstring is at
>> least somewhat inaccurate.
>> 
> 
> 

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-04  5:29     ` Jean-Christophe Helary
@ 2020-01-07  8:41       ` Nicolas Goaziou
  2020-01-31 11:13         ` Bastien
  0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2020-01-07  8:41 UTC (permalink / raw)
  To: Jean-Christophe Helary; +Cc: Emacs Orgmode

Hello,

Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
writes:

>> On Jan 4, 2020, at 14:20, Kisaragi Hiu <mail@kisaragi-hiu.com> wrote:
>> 
>> It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.
>> 
>> Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.
>
> This does look like a potential contribution to the package.

I'm not sure would be pertinent to create a whole section for duration
format: these are not quite as ubiquitous as timestamps. However, they
are used here and there so it may be better to add a few words in the
appropriate sections, the main one being obviously "Effort Estimates".

Anyway, patches welcome! :)


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-07  8:41       ` Nicolas Goaziou
@ 2020-01-31 11:13         ` Bastien
  0 siblings, 0 replies; 9+ messages in thread
From: Bastien @ 2020-01-31 11:13 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Jean-Christophe Helary, Emacs Orgmode

Hi Jean-Christophe,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I'm not sure would be pertinent to create a whole section for duration
> format: these are not quite as ubiquitous as timestamps. However, they
> are used here and there so it may be better to add a few words in the
> appropriate sections, the main one being obviously "Effort Estimates".
>
> Anyway, patches welcome! :)

would you be willing to follow Nicolas' suggestion and send a patch
to enhance the "Effort Estimates" section?

Thanks in advance,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-01-02 19:14 Format of Effort estimates should be mentioned in its Info node Kisaragi Hiu
  2020-01-04  2:55 ` Kyle Meyer
@ 2020-02-01  9:24 ` Bastien
  2020-02-01 16:40   ` Kisaragi Hiu
  1 sibling, 1 reply; 9+ messages in thread
From: Bastien @ 2020-02-01  9:24 UTC (permalink / raw)
  To: Kisaragi Hiu; +Cc: emacs-orgmode

Hi Kisaragi Hiu,

Kisaragi Hiu <mail@kisaragi-hiu.com> writes:

> Currently, the Info node about effort estimates does not mention what
> format should it be written in. This causes confusion, as a user might
> assume that it's the same format as schedulers (10m, 6h, etc.) like I
> did.
>
> Simply mentioning "Effort estimates need to have the format H:MM"
> (copied from the docstring or org-effort-property, the only*
> description of the format I could find) in the Info node would be
> enough.

Yes.  Can you submit a patch against doc/org-manual.org?

Thanks!

-- 
 Bastien

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-02-01  9:24 ` Bastien
@ 2020-02-01 16:40   ` Kisaragi Hiu
  2020-02-01 16:45     ` Bastien
  0 siblings, 1 reply; 9+ messages in thread
From: Kisaragi Hiu @ 2020-02-01 16:40 UTC (permalink / raw)
  To: Bastien; +Cc: Emacs Orgmode

[-- Attachment #1: Type: text/plain, Size: 1254 bytes --]

Done; I haven't done the copyright assignment paperwork with FSF, but I guess it's fine since this is under the 15 line limit?

I copied a few examples from org-duration.el, which is what actually defines the format (org-refresh-effort-estimates). I also corrected the docstring of org-effort-property, as the format does actually allow for values like "10min" or "6h". (I was under the impression that "10m" didn't work because it didn't show up when I asked the agenda to filter to < 60 minutes; it's actually working just fine since that means 10 months.)


2020年2月1日 17:24 差出し人: bzg@gnu.org:

> Hi Kisaragi Hiu,
>
> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>
>> Currently, the Info node about effort estimates does not mention what
>> format should it be written in. This causes confusion, as a user might
>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>> did.
>>
>> Simply mentioning "Effort estimates need to have the format H:MM"
>> (copied from the docstring or org-effort-property, the only*
>> description of the format I could find) in the Info node would be
>> enough.
>>
>
> Yes.  Can you submit a patch against doc/org-manual.org?
>
> Thanks!
>
> -- 
> Bastien
>


[-- Attachment #2: 0001-org-manual.org-Mention-the-format-of-effort-estimate.patch --]
[-- Type: text/x-patch, Size: 1331 bytes --]

From 558ad170a05bb9aaf43e246918cea44d8f8da783 Mon Sep 17 00:00:00 2001
From: Kisaragi Hiu <mail@kisaragi-hiu.com>
Date: Sun, 2 Feb 2020 00:04:23 +0800
Subject: [PATCH 1/2] org-manual.org: Mention the format of effort estimates

* doc/org-manual.org (Effort Estimates): Mention the format of effort
estimates.
---
 doc/org-manual.org | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index ce4fedb55..70a654647 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6899,9 +6899,14 @@ to produce offers with quotations of the estimated work effort, you
 may want to assign effort estimates to entries.  If you are also
 clocking your work, you may later want to compare the planned effort
 with the actual working time, a great way to improve planning
-estimates.  Effort estimates are stored in a special property
-=EFFORT=.  You can set the effort for an entry with the following
-commands:
+estimates.
+
+Effort estimates are stored in a special property =EFFORT=.  Multiple
+formats are supported, such as =3:12=, =1:23:45=, or =1d3h5min=; see
+the file =org-duration.el= for more detailed information about the
+format.
+
+You can set the effort for an entry with the following commands:
 
 - {{{kbd(C-c C-x e)}}}  (~org-set-effort~) ::
 
-- 
2.25.0


[-- Attachment #3: 0002-org.el-Correct-docstring.patch --]
[-- Type: text/x-patch, Size: 887 bytes --]

From e7e7a3205ae6da51a696f45d7afee5f8b98bddac Mon Sep 17 00:00:00 2001
From: Kisaragi Hiu <mail@kisaragi-hiu.com>
Date: Sun, 2 Feb 2020 00:08:10 +0800
Subject: [PATCH 2/2] org.el: Correct docstring

* lisp/org.el (org-effort-property): Correct docstring, as the
previous description of the format was inaccurate.
---
 lisp/org.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/org.el b/lisp/org.el
index 3605460f3..ba34ee38e 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -565,7 +565,8 @@ An entry can be toggled between COMMENT and normal with
 
 (defconst org-effort-property "Effort"
   "The property that is being used to keep track of effort estimates.
-Effort estimates given in this property need to have the format H:MM.")
+Effort estimates given in this property need to be in the format
+defined in org-duration.el.")
 
 ;;;; Timestamp
 
-- 
2.25.0


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: Format of Effort estimates should be mentioned in its Info node
  2020-02-01 16:40   ` Kisaragi Hiu
@ 2020-02-01 16:45     ` Bastien
  0 siblings, 0 replies; 9+ messages in thread
From: Bastien @ 2020-02-01 16:45 UTC (permalink / raw)
  To: Kisaragi Hiu; +Cc: Emacs Orgmode

Hi Kisaragi Hiu,

> Done; I haven't done the copyright assignment paperwork with FSF, but
> I guess it's fine since this is under the 15 line limit?

Yes, thanks a lot.  I've applied your commits to th master branch.  I
just added the TINYCHANGE cookie in the commit messages.

> I copied a few examples from org-duration.el, which is what actually
> defines the format (org-refresh-effort-estimates). I also corrected
> the docstring of org-effort-property, as the format does actually
> allow for values like "10min" or "6h". (I was under the impression
> that "10m" didn't work because it didn't show up when I asked the
> agenda to filter to < 60 minutes; it's actually working just fine
> since that means 10 months.)

Thanks again!

-- 
 Bastien

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-02-01 16:45 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-02 19:14 Format of Effort estimates should be mentioned in its Info node Kisaragi Hiu
2020-01-04  2:55 ` Kyle Meyer
2020-01-04  5:20   ` Kisaragi Hiu
2020-01-04  5:29     ` Jean-Christophe Helary
2020-01-07  8:41       ` Nicolas Goaziou
2020-01-31 11:13         ` Bastien
2020-02-01  9:24 ` Bastien
2020-02-01 16:40   ` Kisaragi Hiu
2020-02-01 16:45     ` Bastien

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).