From mboxrd@z Thu Jan 1 00:00:00 1970 From: Aaron Ecay Subject: Re: [ANN] New Org duration library Date: Wed, 22 Feb 2017 15:33:57 +0000 Message-ID: <87a89etf2y.fsf@trex> References: <87bmu6p4f5.fsf@nicolasgoaziou.fr> <87h93nxxs4.fsf@Rainer.invalid> <8760k3toq2.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56609) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cgYvf-00060V-QD for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 10:34:09 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cgYvZ-0002Ek-SE for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 10:34:07 -0500 Received: from mail-wm0-x244.google.com ([2a00:1450:400c:c09::244]:34214) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cgYvZ-0002ES-K6 for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 10:34:01 -0500 Received: by mail-wm0-x244.google.com with SMTP id 134so307461wmj.1 for ; Wed, 22 Feb 2017 07:33:59 -0800 (PST) In-Reply-To: <8760k3toq2.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Nicolas Goaziou , Achim Gratz Cc: emacs-orgmode@gnu.org Hi Nicolas, hi Achim, 2017ko otsailak 21an, Nicolas Goaziou-ek idatzi zuen: [...] >> Also, I find the documentation to be completely impenetrable. >=20 > 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=CA=BCve pasted that effort at the bot= tom 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=CA=BCt 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 =E2=80=9Cspec= ial=E2=80=9D is a bit confusing. If it isn=CA=BCt 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=CA=BCs in arbitrary order? The documentation doesn=CA=BCt mak= e it clear one way or the other. =3D=3D=3D=3D=3D 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)). =20=20 --=20 Aaron Ecay