[Top][All Lists]

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

[O] [ANN] New Org duration library

From: Nicolas Goaziou
Subject: [O] [ANN] New Org duration library
Date: Mon, 13 Feb 2017 15:10:38 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux)


* 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

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

- 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

    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.


Nicolas Goaziou                                                0x80A93738

reply via email to

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