[ANN] New Org duration library

[ANN] New Org duration library

[Nicolas Goaziou]

Hello,

* TL;DR;

`org-time-clocksum-format', `org-time-clocksum-use-fractional' and
`org-time-clocksum-fractional-format' are obsolete. If you changed them,
consider modifying ~org-duration-format~ instead.

Variable `org-time-clocksum-use-effort-durations' is also obsolete.
Consider setting `org-duration-units' instead.

* Rationale

In current stable version, time duration handling is unsatisfactory:

- There are overlapping and confusing functions:
  `org-minutes-to-clocksum-string', `org-hh:mm-string-to-minutes' and
  `org-duration-string-to-minutes'.

- Duration format is powerful but complex to handle since there are four
  variables involved: `org-time-clocksum-format',
  `org-time-clocksum-use-fractional',
  `org-time-clocksum-fractional-format' and
  `org-time-clocksum-use-effort-durations'.

- More importantly, if you set that format to something fancy, it is not
  possible anymore to read the produced string back.

Therefore, I implemented and merged a simple "duration" library that
takes care of reading and producing such durations. Quoting the file's
commentary:

    This library provides tools to manipulate durations.  A duration
    can have multiple formats:
 
      - 3:12
      - 1:23:45
      - 1y 3d 3h 4min
      - 3d 13:35
      - 2.35h
 
    More accurately, it consists of numbers and units, as defined in
    variable `org-duration-units', separated with white spaces, and
    a "H:MM" or "H:MM:SS" part.  White spaces are tolerated between the
    number and its relative unit.  Variable `org-duration-format'
    controls durations default representation.
 
    The library provides functions allowing to convert a duration to,
    and from, a number of minutes: `org-duration-to-minutes' and
    `org-duration-from-minutes'.  It also provides two lesser tools:
    `org-duration-p', and `org-duration-h:mm-only-p'.
 
    Users can set the number of minutes per unit, or define new units,
    in `org-duration-units'.  The library also supports canonical
    duration, i.e., a duration that doesn't depend on user's settings,
    through optional arguments.

At the cost of some incompatibilities if you introduced some fancy
duration format, and a slightly more limited choice of representation,
we get a more consistent and sturdy interface.

* About base unit design choice

The base unit for a duration is the minute. I hesitated with the more
natural second but

- Org time precision is the minute,

- `org-duration-to-minutes' and `org-duration-from-minutes' can be
  drop-in replacements for the functions quoted above,

- We would need to handle floats anyway as we don't require custom units
  to be multiple of the base unit.


Feedback welcome.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [ANN] New Org duration library

[Detlef Steuer]

Dear Nicolas,

after updating org this morning from git I get:

org-duration-to-minutes: Invalid duration format: " 9:00"

if I try to invoke my agenda with C-c a a

What gives me headaches: I don't use, AFAIK, durations anywhere
and a grep over my org files shows *no* occurence of " 9:00".

This is the complete relevant part of the message buffer:

org-duration-to-minutes: Invalid duration format: " 9:00"
Quit
Making completion list... [2 times]
Quit [4 times]
Saving file /home/steuer/.emacs.d/init.el...
Wrote /home/steuer/.emacs.d/init.el
Press key for agenda command (unrestricted):
org-duration-to-minutes: Invalid duration format: " 9:00"

Any idea? My agenda is inaccessible for me at the moment, what is
not so nice.

Regards
Detlef

Am Mon, 13 Feb 2017 15:10:38 +0100
schrieb Nicolas Goaziou <mail@nicolasgoaziou.fr>:

> Hello,
> 
> * TL;DR;
> 
> `org-time-clocksum-format', `org-time-clocksum-use-fractional' and
> `org-time-clocksum-fractional-format' are obsolete. If you changed
> them, consider modifying ~org-duration-format~ instead.
> 
> Variable `org-time-clocksum-use-effort-durations' is also obsolete.
> Consider setting `org-duration-units' instead.
> 
> * Rationale
> 
> In current stable version, time duration handling is unsatisfactory:
> 
> - There are overlapping and confusing functions:
>   `org-minutes-to-clocksum-string', `org-hh:mm-string-to-minutes' and
>   `org-duration-string-to-minutes'.
> 
> - Duration format is powerful but complex to handle since there are
> four variables involved: `org-time-clocksum-format',
>   `org-time-clocksum-use-fractional',
>   `org-time-clocksum-fractional-format' and
>   `org-time-clocksum-use-effort-durations'.
> 
> - More importantly, if you set that format to something fancy, it is
> not possible anymore to read the produced string back.
> 
> Therefore, I implemented and merged a simple "duration" library that
> takes care of reading and producing such durations. Quoting the file's
> commentary:
> 
>     This library provides tools to manipulate durations.  A duration
>     can have multiple formats:
>  
>       - 3:12
>       - 1:23:45
>       - 1y 3d 3h 4min
>       - 3d 13:35
>       - 2.35h
>  
>     More accurately, it consists of numbers and units, as defined in
>     variable `org-duration-units', separated with white spaces, and
>     a "H:MM" or "H:MM:SS" part.  White spaces are tolerated between
> the number and its relative unit.  Variable `org-duration-format'
>     controls durations default representation.
>  
>     The library provides functions allowing to convert a duration to,
>     and from, a number of minutes: `org-duration-to-minutes' and
>     `org-duration-from-minutes'.  It also provides two lesser tools:
>     `org-duration-p', and `org-duration-h:mm-only-p'.
>  
>     Users can set the number of minutes per unit, or define new units,
>     in `org-duration-units'.  The library also supports canonical
>     duration, i.e., a duration that doesn't depend on user's settings,
>     through optional arguments.
> 
> At the cost of some incompatibilities if you introduced some fancy
> duration format, and a slightly more limited choice of representation,
> we get a more consistent and sturdy interface.
> 
> * About base unit design choice
> 
> The base unit for a duration is the minute. I hesitated with the more
> natural second but
> 
> - Org time precision is the minute,
> 
> - `org-duration-to-minutes' and `org-duration-from-minutes' can be
>   drop-in replacements for the functions quoted above,
> 
> - We would need to handle floats anyway as we don't require custom
> units to be multiple of the base unit.
> 
> 
> Feedback welcome.
> 
> Regards,
> 



-- 

"Wisely and slow. Those stumble that run fast."
Shakespeare -- Romeo and Juliet

Dr. Detlef Steuer
Helmut-Schmidt-Universität
Fakultät WiSo
Holstenhofweg 85
22043 Hamburg

Tel:  040/6541-2819
mail: steuer@hsu-hh.de

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

Detlef Steuer <steuer@unibw-hamburg.de> writes:

> after updating org this morning from git I get:
>
> org-duration-to-minutes: Invalid duration format: " 9:00"
>
> if I try to invoke my agenda with C-c a a
>
> What gives me headaches: I don't use, AFAIK, durations anywhere
> and a grep over my org files shows *no* occurence of " 9:00".
>
> This is the complete relevant part of the message buffer:
>
> org-duration-to-minutes: Invalid duration format: " 9:00"
> Quit
> Making completion list... [2 times]
> Quit [4 times]
> Saving file /home/steuer/.emacs.d/init.el...
> Wrote /home/steuer/.emacs.d/init.el
> Press key for agenda command (unrestricted):
> org-duration-to-minutes: Invalid duration format: " 9:00"
>
> Any idea? My agenda is inaccessible for me at the moment, what is
> not so nice.

I didn't allow leading or trailing blanks in durations. Apparently,
Agenda needs this. So I updated the regexps.

Please update Org and tell me if it works now.

Regards,

-- 
Nicolas Goaziou

Re: [ANN] New Org duration library

[Detlef Steuer]

Yes, works now!

Many thx!

Detlef

Am Tue, 14 Feb 2017 10:01:52 +0100
schrieb Nicolas Goaziou <mail@nicolasgoaziou.fr>:

> Hello,
> 
> Detlef Steuer <steuer@unibw-hamburg.de> writes:
> 
> > after updating org this morning from git I get:
> >
> > org-duration-to-minutes: Invalid duration format: " 9:00"
> >
> > if I try to invoke my agenda with C-c a a
> >
> > What gives me headaches: I don't use, AFAIK, durations anywhere
> > and a grep over my org files shows *no* occurence of " 9:00".
> >
> > This is the complete relevant part of the message buffer:
> >
> > org-duration-to-minutes: Invalid duration format: " 9:00"
> > Quit
> > Making completion list... [2 times]
> > Quit [4 times]
> > Saving file /home/steuer/.emacs.d/init.el...
> > Wrote /home/steuer/.emacs.d/init.el
> > Press key for agenda command (unrestricted):
> > org-duration-to-minutes: Invalid duration format: " 9:00"
> >
> > Any idea? My agenda is inaccessible for me at the moment, what is
> > not so nice.  
> 
> I didn't allow leading or trailing blanks in durations. Apparently,
> Agenda needs this. So I updated the regexps.
> 
> Please update Org and tell me if it works now.
> 
> Regards,
> 



-- 

"Wisely and slow. Those stumble that run fast."
Shakespeare -- Romeo and Juliet

Dr. Detlef Steuer
Helmut-Schmidt-Universität
Fakultät WiSo
Holstenhofweg 85
22043 Hamburg

Tel:  040/6541-2819
mail: steuer@hsu-hh.de

Re: [ANN] New Org duration library

[David Mann]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Detlef Steuer <steuer@unibw-hamburg.de> writes:
>
>> after updating org this morning from git I get:
>>
>> org-duration-to-minutes: Invalid duration format: " 9:00"
>>
>> if I try to invoke my agenda with C-c a a
>>
>> What gives me headaches: I don't use, AFAIK, durations anywhere
>> and a grep over my org files shows *no* occurence of " 9:00".
>>
>> This is the complete relevant part of the message buffer:
>>
>> org-duration-to-minutes: Invalid duration format: " 9:00"
>> Quit
>> Making completion list... [2 times]
>> Quit [4 times]
>> Saving file /home/steuer/.emacs.d/init.el...
>> Wrote /home/steuer/.emacs.d/init.el
>> Press key for agenda command (unrestricted):
>> org-duration-to-minutes: Invalid duration format: " 9:00"
>>
>> Any idea? My agenda is inaccessible for me at the moment, what is
>> not so nice.
>
> I didn't allow leading or trailing blanks in durations. Apparently,
> Agenda needs this. So I updated the regexps.
>
> Please update Org and tell me if it works now.
>
> Regards,

I am having a similar problem with my agenda since updating Org to
9.0.5.  Since seems to be after the fix above.  I get a message 'Invalid
duration format: "50%".

I am using org from git:
Org mode version 9.0.5 (release_9.0.5-333-g8a1649 @
/Users/mannd/git/org-mode/lisp/)

Emacs version is:
GNU Emacs 25.1.50.1 (x86_64-apple-darwin15.3.0, NS appkit-1404.34
Version 10.11.3 (Build 15D21)) of 2016-03-13

thanks,
David Mann

Re: [ANN] New Org duration library

[David Mann]

David Mann <manndmd@gmail.com> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Hello,
>>
>> Detlef Steuer <steuer@unibw-hamburg.de> writes:
>>
>>> after updating org this morning from git I get:
>>>
>>> org-duration-to-minutes: Invalid duration format: " 9:00"
>>>
>>> if I try to invoke my agenda with C-c a a
>>>
>>> What gives me headaches: I don't use, AFAIK, durations anywhere
>>> and a grep over my org files shows *no* occurence of " 9:00".
>>>
>>> This is the complete relevant part of the message buffer:
>>>
>>> org-duration-to-minutes: Invalid duration format: " 9:00"
>>> Quit
>>> Making completion list... [2 times]
>>> Quit [4 times]
>>> Saving file /home/steuer/.emacs.d/init.el...
>>> Wrote /home/steuer/.emacs.d/init.el
>>> Press key for agenda command (unrestricted):
>>> org-duration-to-minutes: Invalid duration format: " 9:00"
>>>
>>> Any idea? My agenda is inaccessible for me at the moment, what is
>>> not so nice.
>>
>> I didn't allow leading or trailing blanks in durations. Apparently,
>> Agenda needs this. So I updated the regexps.
>>
>> Please update Org and tell me if it works now.
>>
>> Regards,
>
> I am having a similar problem with my agenda since updating Org to
> 9.0.5.  Since seems to be after the fix above.  I get a message 'Invalid
> duration format: "50%".
>
> I am using org from git:
> Org mode version 9.0.5 (release_9.0.5-333-g8a1649 @
> /Users/mannd/git/org-mode/lisp/)
>
> Emacs version is:
> GNU Emacs 25.1.50.1 (x86_64-apple-darwin15.3.0, NS appkit-1404.34
> Version 10.11.3 (Build 15D21)) of 2016-03-13
>
> thanks,
> David Mann

I will add that this problem does not appear in the tagged release_9.0.5
version.

DEM

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

David Mann <manndmd@gmail.com> writes:

> I am having a similar problem with my agenda since updating Org to
> 9.0.5.  Since seems to be after the fix above.  I get a message 'Invalid
> duration format: "50%".

Could you paste the full backtrace? Do you have an idea about where that
"50%" comes from?

Regards,

-- 
Nicolas Goaziou

Re: [ANN] New Org duration library

[Achim Gratz]

Nicolas Goaziou writes:
> `org-time-clocksum-format', `org-time-clocksum-use-fractional' and
> `org-time-clocksum-fractional-format' are obsolete. If you changed them,
> consider modifying ~org-duration-format~ instead.

You seem to have (some of) these aliased to org-duration format somehow.
This breaks a lot of things because the format of the former variables
is not recognized.  I got a bunch of errors about :hour not being a list
for instance.  There surely must be a better way to handle the
transition?

Also, I find the documentation to be completely impenetrable.
Customization has offered to create a setting for org-duration-format
that's not even mentioned in the documentation.

Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

Achim Gratz <Stromeko@nexgo.de> writes:

> You seem to have (some of) these aliased to org-duration format somehow.
> This breaks a lot of things because the format of the former variables
> is not recognized.  I got a bunch of errors about :hour not being a list
> for instance.  There surely must be a better way to handle the
> transition?

Fixed. Thank you.

> Also, I find the documentation to be completely impenetrable.

Great. Suggestions welcome.

> Customization has offered to create a setting for org-duration-format
> that's not even mentioned in the documentation.

Would it be possible, by any chance, to get a glimpse of that setting?

Regards,

-- 
Nicolas Goaziou

Re: [ANN] New Org duration library

[Achim Gratz]

Nicolas Goaziou writes:
>> You seem to have (some of) these aliased to org-duration format somehow.
>> This breaks a lot of things because the format of the former variables
>> is not recognized.  I got a bunch of errors about :hour not being a list
>> for instance.  There surely must be a better way to handle the
>> transition?
>
> Fixed. Thank you.

Thanks, but will there be some helper function to migrate the old
customizations?  I didn't even remember that I had customized this
variable until I couldn't clock in or out anymore (I remember now that I
customized it so it would record durations in hours, not days/hours).

>> Also, I find the documentation to be completely impenetrable.
>
> Great. Suggestions welcome.

I'd first need to understand what the options there really mean.  It
seems that the variable can be set to just a symbol or (maybe) a string
or a list of conses.  The conses form refer to org-duration-units, but
there the units are all defined as strings and no mention of the symbol
special that apparently is another possibility.  I don't really see why
you'd mix symbols and strings in the same position.  I have no idea what
"mixed mode" is supposed to be and what happens if I specify both
(special . h:mm) and ("h" . nil) for instance.  Is the order of these
important?

>> Customization has offered to create a setting for org-duration-format
>> that's not even mentioned in the documentation.
>
> Would it be possible, by any chance, to get a glimpse of that setting?

I've set it to the symbol h:mm (shown as H:MM in customize) via the
value menu in customize.  I might read the documentation incorrectly,
but to me it seems to say it should be the string "h:mm" instead.  I'm
left to wonder if (h:mm) is the same or different from ((special . h.mm)).


Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Achim Gratz <Stromeko@nexgo.de> writes:

> Thanks, but will there be some helper function to migrate the old
> customizations?  I didn't even remember that I had customized this
> variable until I couldn't clock in or out anymore (I remember now that I
> customized it so it would record durations in hours, not days/hours).

A helper function is not really possible since there is no 1 to
1 equivalence between the two systems. They share the same default
value, tho.

You can post your old customization here, I try to help you convert it
to the new format, if possible at all.

> I'd first need to understand what the options there really mean.  It
> seems that the variable can be set to just a symbol or (maybe) a string
> or a list of conses.

Strings are not allowed. It is either a symbol (h:mm:ss or h:mm) or
a list of conses.

> The conses form refer to org-duration-units, but there the units are
> all defined as strings and no mention of the symbol special that
> apparently is another possibility.

The mention of the symbol special is there:

  Eventually, the list can contain an entry indicating special
  formatting needs.  It can follow one of the three following
  patterns:

    (special . h:mm)
    (special . h:mm:ss)
    (special . PRECISION)

  When any of the first two is present, a duration is expressed in
  mixed mode, where the hours and minutes of the duration are
  expressed as a \"H:MM:SS\" or \"H:MM\" string while still using
  other units defined.

> I don't really see why you'd mix symbols and strings in the same
> position.

Probably because I couldn't find a better idea to cover all cases.

> I have no idea what "mixed mode" is supposed to be

The definition of "mixed mode" is in the docstring:

  When any of the first two is present, a duration is expressed in
  mixed mode, where the hours and minutes of the duration are
  expressed as a \"H:MM:SS\" or \"H:MM\" string while still using
  other units defined.

There is even an example in the docstring:

  The following format

    ((\"d\" . nil) (special . h:mm))

  means that any duration longer than a day is expressed with both
  a \"d\" unit and a \"H:MM\" part, whereas a duration shorter than
  a day is expressed only as a \"H:MM\" string.

Basically,

  1d 8:30

is mixed mode.

> and what happens if I specify both (special . h:mm) and ("h" . nil)
> for instance. Is the order of these important?

Specifying both (special . h:mm) and ("h" . nil) is nonsensical, since
you request something like "0:30" in the first case, and "0h" in the
second one.

In this case, I think ("h" . nil) is going to be ignored since (special
. h:mm) already takes care of hours an minutes.

> I've set it to the symbol h:mm (shown as H:MM in customize) via the
> value menu in customize.  I might read the documentation incorrectly,
> but to me it seems to say it should be the string "h:mm" instead.

The first paragraph of the docstring is

  The value can be set to, respectively, `h:mm:ss' or `h:mm', which
  means a duration is expressed as, respectively, a \"H:MM:SS\" or
  \"H:MM\" string.

`...' implies a symbol, so `h:mm' is definitely a correct value. 

> I'm left to wonder if (h:mm) is the same or different from ((special .
> h.mm)).

There is no such thing as (h:mm). However, 'h:mm is morally equivalent
to ((special . h:mm)).

HTH,

Re: [ANN] New Org duration library

[Achim Gratz]

Nicolas Goaziou writes:
> You can post your old customization here, I try to help you convert it
> to the new format, if possible at all.

Well, once I remembered why I had to customize it, things fell into
place.  It wasn't something complicated, just that I wanted all
durations shown in h:mm, without days (for the timetable at work).

>> I'd first need to understand what the options there really mean.  It
>> seems that the variable can be set to just a symbol or (maybe) a string
>> or a list of conses.
>
> Strings are not allowed. It is either a symbol (h:mm:ss or h:mm) or
> a list of conses.

That sentence in the documentation would have helped.

>> I don't really see why you'd mix symbols and strings in the same
>> position.
>
> Probably because I couldn't find a better idea to cover all cases.

If units are defined as strings, then why can the format not be a string
also?  I still find this confusing, especially as there are multiple
other places in Org that use format strings quite happily.

>> I have no idea what "mixed mode" is supposed to be
>
> The definition of "mixed mode" is in the docstring:
>
>   When any of the first two is present, a duration is expressed in
>   mixed mode, where the hours and minutes of the duration are
>   expressed as a \"H:MM:SS\" or \"H:MM\" string while still using
>   other units defined.

Lost me right there again.  Please tell the user what problem he can
solve with this and then tell him how to do it, not the other way
around.  So, the purpose of this variable is to specify how you want
durations displayed in Org, using the predefined "special" formats or
user-defined org-duration units (there's a default on those as well).  A
duration format doesn't necessarily use all defined units, and of those
it is using it (always?) starts with the largest unit and ends with the
smallest.  This is the only one that can usefully have PRECISION, I
suppose, but the docstring shows there might be a possibility to chose
differently (I believe that means it ignores the smaller units in this
case).

> There is even an example in the docstring:
>
>   The following format
>
>     ((\"d\" . nil) (special . h:mm))

Except the default really is shown as (("d") (special . h:mm)) if the
user cares to look things up.

>   means that any duration longer than a day is expressed with both
>   a \"d\" unit and a \"H:MM\" part, whereas a duration shorter than
>   a day is expressed only as a \"H:MM\" string.
>
> Basically,
>
>   1d 8:30
>
> is mixed mode.
>
>> and what happens if I specify both (special . h:mm) and ("h" . nil)
>> for instance. Is the order of these important?
>
> Specifying both (special . h:mm) and ("h" . nil) is nonsensical, since
> you request something like "0:30" in the first case, and "0h" in the
> second one.
>
> In this case, I think ("h" . nil) is going to be ignored since (special
> . h:mm) already takes care of hours an minutes.

I've picked something that I expected to be nonsensical on purpose,
although I think it wouldn't be entirely unreasonable for a user to
expect that the duration would simply get formatted both ways.  The
documentation should tell me not to do that or if it's ignoring part of
the specification.  I take from your answer that the order of
specification might not be important, but it's not spelled out in the
docstring yet.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

Achim Gratz <Stromeko@nexgo.de> writes:

> Nicolas Goaziou writes:

>> Strings are not allowed. It is either a symbol (h:mm:ss or h:mm) or
>> a list of conses.
>
> That sentence in the documentation would have helped.

The documentation lists what is allowed. Strings are not. Where did you
read that they might be? For the record, here are the first paragraphs
of the docstring:

  The value can be set to, respectively, ‘h:mm:ss’ or ‘h:mm’, which
  means a duration is expressed as, respectively, a "H:MM:SS" or
  "H:MM" string.

  Alternatively, the value can be a list of entries following the
  pattern:

    (UNIT . REQUIRED?)

This is basically the same as "It is either a symbol (h:mm:ss or h:mm)
or a list of conses".

In any case, it is unreasonable, IMO, to also document all that is _not_
allowed.

> If units are defined as strings, then why can the format not be a string
> also?  I still find this confusing, especially as there are multiple
> other places in Org that use format strings quite happily.

I'm not sure to understand your suggestion. Are you suggesting to use
a format control string, e.g., as expected by `format-seconds'? The
problems with format strings are that:

- you cannot guarantee to be able to read the duration back into
  minutes, e.g., for some convoluted format strings;

- it is much less powerful than the current variable. In particular, it
  is not possible to have mixed mode with a format string. It is not
  possible to have conditional durations (e.g., one format for more than
  a day, another one for less than one) either;

> Lost me right there again.  Please tell the user what problem he can
> solve with this and then tell him how to do it, not the other way
> around.

There is no problem to solve. It is about aesthetics.
`org-duration-to-minutes' understands every possible format defined with
`org-duration-format' anyway.

Since I cannot foretell what a user is going to want, I simply describe
what is possible to do, and how.

Again, feel free to suggest more precise suggestions.

> So, the purpose of this variable is to specify how you want durations
> displayed in Org, using the predefined "special" formats or
> user-defined org-duration units (there's a default on those as well).

Correct. As a reminder, the first sentence of the docstring is:

  Format definition for a duration.

> A duration format doesn't necessarily use all defined units,

Correct.

> and of those it is using it (always?) starts with the largest unit and
> ends with the smallest.

Not necessarily. Considering (("d" . nil) ("h" . nil) ("min" . nil)),
180 minutes become "3h". Neither the largest nor the smallest units are
used.

> This is the only one that can usefully have PRECISION, I suppose, but
> the docstring shows there might be a possibility to chose differently
> (I believe that means it ignores the smaller units in this case).

The docstring is right. PRECISION implies a single unit is used, but you
can control which one. For example, with 

  ((d . nil) (h . nil) (special . 1))

390 minutes are spelled "6.5h", but 1440 minutes become "1.0d".

Note that, using ((d . nil) (special . 1)) instead, 390 minutes is
"0.3d".

>> There is even an example in the docstring:
>>
>>   The following format
>>
>>     ((\"d\" . nil) (special . h:mm))
>
> Except the default really is shown as (("d") (special . h:mm)) if the
> user cares to look things up.

As you well know, ("d" . nil) is exactly ("d"). I spelled out the nil
part so it matches the expected pattern clearly. What is the problem
here?

> I've picked something that I expected to be nonsensical on purpose,
> although I think it wouldn't be entirely unreasonable for a user to
> expect that the duration would simply get formatted both ways.

Hmm, what? How do you format a duration "both ways"? You cannot write,
e.g., "30min 0:30": it could be interpreted as a convoluted way to say
"1h".

> The documentation should tell me not to do that or if it's ignoring
> part of the specification.

I re-worded that last part of the documentation:

  Eventually, the list can contain one of the following special
  entries:

    (special . h:mm)
    (special . h:mm:ss)

      Units shorter than an hour are ignored.  The hours and
      minutes part of the duration is expressed unconditionally
      with H:MM, or H:MM:SS, pattern.

    (special . PRECISION)

      A duration is expressed with a single unit, PRECISION being
      the number of decimal places to show.  The unit chosen is the
      first one required or with a non-zero integer part.  If there
      is no such unit, the smallest one is used.

Hopefully, it is clearer now.

> I take from your answer that the order of specification might not be
> important, but it's not spelled out in the docstring yet.

The order of specification _is_ important, as in any alist. I don't
think every variable using alists reminds the user about this.

In the case above, though, the order is not important because 

  (special . h:mm)

implies that ("h" . nil) is ignored. I tried to make this more obvious
in the rewording above.

Regards,

-- 
Nicolas Goaziou

Re: [ANN] New Org duration library

[Malcolm Purvis]

>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

Nicolas> The documentation lists what is allowed. Strings are not. Where
Nicolas> did you read that they might be? For the record, here are the
Nicolas> first paragraphs of the docstring:

Nicolas>   The value can be set to, respectively, ‘h:mm:ss’ or ‘h:mm’,
Nicolas> which means a duration is expressed as, respectively, a
Nicolas> "H:MM:SS" or "H:MM" string.

I too was confused by this and took the quotes around ‘h:mm:ss’ and
‘h:mm’ to mean that they are strings.  Changing the working to be:

   The value can be set to, respectively, the symbols ‘h:mm:ss’ or ‘h:mm’,

would clarify the situation.

Malcolm

-- 
	       Malcolm Purvis <malcolm@purvis.id.au>

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

Malcolm Purvis <malcolm@purvis.id.au> writes:

>>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
> Nicolas> The documentation lists what is allowed. Strings are not. Where
> Nicolas> did you read that they might be? For the record, here are the
> Nicolas> first paragraphs of the docstring:
>
> Nicolas>   The value can be set to, respectively, ‘h:mm:ss’ or ‘h:mm’,
> Nicolas> which means a duration is expressed as, respectively, a
> Nicolas> "H:MM:SS" or "H:MM" string.
>
> I too was confused by this and took the quotes around ‘h:mm:ss’ and
> ‘h:mm’ to mean that they are strings.  Changing the working to be:
>
>    The value can be set to, respectively, the symbols ‘h:mm:ss’ or ‘h:mm’,
>
> would clarify the situation.

I made that change. Thank you.

Regards,

-- 
Nicolas Goaziou

Re: [ANN] New Org duration library

[Aaron Ecay]

Hi Nicolas, hi Achim,

2017ko otsailak 21an, Nicolas Goaziou-ek idatzi zuen:

[...]

>> Also, I find the documentation to be completely impenetrable.
> 
> Great. Suggestions welcome.

I took a look at the docstring.  I think I managed to understand it, but
I can see how it might be confusing.  I made an attempt to restructure
it to explain first the general cases and then the exceptions, which is
a clearer order (at least to me).  I also changed some minor things that
hopefully make it clearer overall.  Iʼve pasted that effort at the bottom
of this email.

I had a few questions/comments though:

- Given that the smallest unit of duration is the minute, why are
  seconds a choice in h:mm:ss?  Wonʼt they always be zero?  Maybe it is
  better not to offer this choice; I think it is potentially confusing
  (giving the impression that durations might be accurate to the
  second).
- I would remove the h:mm symbol shorthand.  It can still be offered as
  a convenient option in customize using (const :tag "Use H:MM" (special
  . h:mm)), but making it a special value with its own semantics makes
  the system harder to understand for those who write their config in
  lisp (rather than using customize).
- The fact that the special options are grouped under the key “special”
  is a bit confusing.  If it isnʼt too much work, I would recommend
  restructuring the options slightly to be (use-h:mm . t) and (precision
  . INT).  This more closely matches my intuition about how alists like
  this are used.
- Must the list be in decreasing order of unit size, or does everything
  work if itʼs in arbitrary order?  The documentation doesnʼt make it
  clear one way or the other.

=====

Format definition for a duration.

The value should be a list of entries each following this pattern:

  (UNIT . REQUIRED)

UNIT is one of the unit strings defined in `org-duration-units'.  A
duration is formatted using only the time components that are specified
here.  If a time unit in missing, formatting falls back to the next
smallest unit.

A non-nil REQUIRED value for these keys indicates that the
corresponding time component should always be included, even if
its value is 0.

For example,

   ((\"d\" . nil) (\"h\" . t) (\"min\" . t))

means a duration longer than a day is expressed in days, hours
and minutes, whereas a duration shorter than a day is always
expressed in hours and minutes, even when shorter than an hour.

On the other hand, the value

  ((\"d\" . nil) (\"min\" . nil))

means a duration longer than a day is expressed in days and
minutes, whereas a duration shorter than a day is expressed
entirely in minutes, even when longer than an hour.

At the end of the list, there can be an entry indicating special formatting
needs.  It must follow one of the three following patterns:

  (special . h:mm)
  (special . h:mm:ss)
  (special . PRECISION)

When one of the first two is present, a duration is expressed in mixed
mode, where larger units are used down to hours, then the remaining
hours and minutes of the duration are expressed as a \"H:MM:SS\" or
\"H:MM\" string.

With the last pattern, a duration is always expressed with a single
unit.  PRECISION, an integer, indicates the number of decimal places to
show.  The unit chosen is the first one required or with a non-zero
integer part.  If there is no such unit, the smallest one is used.

Thus, the following format

  ((\"d\" . nil) (special . h:mm))

means that any duration longer than a day is expressed as a whole number
of days plus a \"H:MM\" part, whereas a duration shorter than a day is
expressed only as a \"H:MM\" string.

The following format

  ((\"d\" . nil) (\"h\" . nil) (special . 2))

expresses a duration longer than a day as a multiple of a day, accurate
to two decimal places.  A duration shorter than a day uses units of an
hour instead.

Finally, the value can be set to the symbols `h:mm:ss' or `h:mm', which
means a duration, whatever its length, is expressed as a \"H:MM:SS\" or
\"H:MM\" string respectively.  These options are convenient shorthand
which is equivalent to ((special . h:mm:ss)) or ((special . h:mm)).
  
-- 
Aaron Ecay

Re: [ANN] New Org duration library

[Nicolas Goaziou]

Hello,

Aaron Ecay <aaronecay@gmail.com> writes:

> I had a few questions/comments though:
>
> - Given that the smallest unit of duration is the minute,

The base unit is the minute, but nobody prevents you from adding
a smaller unit:

  (let ((org-duration-units (cons `("s" . ,(/ 1 60.0)) org-duration-units)))
    (org-duration-from-minutes 1.5 '(("min") ("s"))))

  => "1min 30s"

>   why are seconds a choice in h:mm:ss?  Wonʼt they always be zero?

Internally, durations are floats because of seconds.

  (org-duration-from-minutes 1.5 'h:mm:ss) => "0:01:30"

>   Maybe it is
>   better not to offer this choice; I think it is potentially confusing
>   (giving the impression that durations might be accurate to the
>   second).

Durations _can_ be accurate to the second. This library can be used
outside clocksum computations, which are, indeed, accurate only to the
minute.

> - I would remove the h:mm symbol shorthand.  It can still be offered as
>   a convenient option in customize using (const :tag "Use H:MM" (special
>   . h:mm)), but making it a special value with its own semantics makes
>   the system harder to understand for those who write their config in
>   lisp (rather than using customize).

Using a list means you want to use special units to display the
duration. However when the value is '((special . h:mm)), there is no
unit to display the duration with, so '((special . h:mm)) is the
degenerate case, not `h:mm'.

Mind you, I'm not opposed to removing `h:mm'. I'm just pointing out the
rational behind the initial choice.

Moreover, if we remove `h:mm', we need to replace calls like

  (org-duration-from-minutes 120 'h:mm)

with

  (org-duration-from-minutes 120 '((special . h:mm)))

which is slightly uglier.

> - The fact that the special options are grouped under the key “special”
>   is a bit confusing.  If it isnʼt too much work, I would recommend
>   restructuring the options slightly to be (use-h:mm . t) and (precision
>   . INT).  This more closely matches my intuition about how alists like
>   this are used.

I chose `special' for a reason: these options are mutually exclusive.
Using the same key, the structure (i.e., the alist) makes them mutually
exclusive, too. With your suggestion, however, nothing prevents an user
to have

  '((use-h:mm . t) (precision . 2))

and complain if strange things happen.

So, I'd rather keep the same car. I'm not married to `special' though.

> - Must the list be in decreasing order of unit size, or does everything
>   work if itʼs in arbitrary order?  The documentation doesnʼt make it
>   clear one way or the other.

There is no restriction about the order.

> The value should be a list of entries each following this pattern:
>
>   (UNIT . REQUIRED)

I'd favor REQUIRED? over REQUIRED because it is a boolean.

> UNIT is one of the unit strings defined in `org-duration-units'.  A
> duration is formatted using only the time components that are specified
> here.  If a time unit in missing, formatting falls back to the next
> smallest unit.

The algorithm works the other way: it consider biggest units first
(greedy algorithm).

> At the end of the list, there can be an entry indicating special formatting

"The end of the list" is not accurate. The entry can be anywhere.

Also, I reworded that part already in master. You may want to have
a look at it.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738