Re: Format of Effort estimates should be mentioned in its Info node

[Kisaragi Hiu <mail@kisaragi-hiu.com>]

[-- 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