From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: [ANN] New Org duration library Date: Wed, 22 Feb 2017 11:56:44 +0100 Message-ID: <871suqh4sz.fsf@nicolasgoaziou.fr> References: <87bmu6p4f5.fsf@nicolasgoaziou.fr> <87h93nxxs4.fsf@Rainer.invalid> <8760k3toq2.fsf@nicolasgoaziou.fr> <87d1ebxv29.fsf@Rainer.invalid> <87d1ebgyy1.fsf@nicolasgoaziou.fr> <87r32rtjgr.fsf@Rainer.invalid> 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]:46103) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cgUbM-0008NK-UZ for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 05:56:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cgUbL-0007Mx-J8 for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 05:56:53 -0500 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:55378) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cgUbL-0007Md-9l for emacs-orgmode@gnu.org; Wed, 22 Feb 2017 05:56:51 -0500 In-Reply-To: <87r32rtjgr.fsf@Rainer.invalid> (Achim Gratz's message of "Tue, 21 Feb 2017 20:47:00 +0100") 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: Achim Gratz Cc: emacs-orgmode@gnu.org Hello, Achim Gratz 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, =E2=80=98h:mm:ss=E2=80=99 or =E2= =80=98h:mm=E2=80=99, 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=20 ((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=20 (special . h:mm) implies that ("h" . nil) is ignored. I tried to make this more obvious in the rewording above. Regards, --=20 Nicolas Goaziou