emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [ANN] New Org duration library
@ 2017-02-13 14:10 Nicolas Goaziou
  2017-02-14  8:17 ` Detlef Steuer
  2017-02-21 17:24 ` Achim Gratz
  0 siblings, 2 replies; 17+ messages in thread
From: Nicolas Goaziou @ 2017-02-13 14:10 UTC (permalink / raw)
  To: Org Mode List

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

^ permalink raw reply	[flat|nested] 17+ messages in thread

end of thread, other threads:[~2017-03-17  8:00 UTC | newest]

Thread overview: 17+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-02-13 14:10 [ANN] New Org duration library Nicolas Goaziou
2017-02-14  8:17 ` Detlef Steuer
2017-02-14  9:01   ` Nicolas Goaziou
2017-02-14  9:10     ` Detlef Steuer
2017-03-03  2:31     ` David Mann
2017-03-03  2:46       ` David Mann
2017-03-03 11:24       ` Nicolas Goaziou
2017-02-21 17:24 ` Achim Gratz
2017-02-21 17:53   ` Nicolas Goaziou
2017-02-21 18:22     ` Achim Gratz
2017-02-21 18:51       ` Nicolas Goaziou
2017-02-21 19:47         ` Achim Gratz
2017-02-22 10:56           ` Nicolas Goaziou
2017-02-22 11:50             ` Malcolm Purvis
2017-03-17  8:00               ` Nicolas Goaziou
2017-02-22 15:33     ` Aaron Ecay
2017-02-22 19:01       ` Nicolas Goaziou

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).