Re: [ANN] New Org duration library

[Aaron Ecay <aaronecay@gmail.com>]

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