emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] [ANN] New Org duration library


From: Nicolas Goaziou
Subject: Re: [O] [ANN] New Org duration library
Date: Wed, 22 Feb 2017 11:56:44 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux)

Hello,

Achim Gratz <address@hidden> 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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]