Re: [ANN] New Org duration library

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

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,