From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#32931: time-stamp-format: offer numeric time zones too Date: Sat, 09 Nov 2019 09:15:32 +0200 Message-ID: <83pni1a5bf.fsf@gnu.org> References: <2074.1573258177@tigger3.sg.gildea.net> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="190575"; mail-complaints-to="usenet@blaine.gmane.org" Cc: rpluim@gmail.com, 32931@debbugs.gnu.org, jidanni@jidanni.org To: Stephen Gildea Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Nov 09 08:16:14 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iTKyk-000nR0-D1 for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Nov 2019 08:16:14 +0100 Original-Received: from localhost ([::1]:35176 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iTKyi-0000mT-J1 for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Nov 2019 02:16:12 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33728) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iTKyZ-0000m3-P3 for bug-gnu-emacs@gnu.org; Sat, 09 Nov 2019 02:16:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iTKyY-0001Ab-Es for bug-gnu-emacs@gnu.org; Sat, 09 Nov 2019 02:16:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:39277) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iTKyY-0001AL-Bh for bug-gnu-emacs@gnu.org; Sat, 09 Nov 2019 02:16:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iTKyY-0003zV-4H for bug-gnu-emacs@gnu.org; Sat, 09 Nov 2019 02:16:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 09 Nov 2019 07:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 32931 X-GNU-PR-Package: emacs Original-Received: via spool by 32931-submit@debbugs.gnu.org id=B32931.157328375315323 (code B ref 32931); Sat, 09 Nov 2019 07:16:02 +0000 Original-Received: (at 32931) by debbugs.gnu.org; 9 Nov 2019 07:15:53 +0000 Original-Received: from localhost ([127.0.0.1]:48098 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iTKyO-0003z4-Os for submit@debbugs.gnu.org; Sat, 09 Nov 2019 02:15:53 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:52834) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iTKyM-0003yo-Rv for 32931@debbugs.gnu.org; Sat, 09 Nov 2019 02:15:51 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:36296) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iTKyD-0000Ow-5j; Sat, 09 Nov 2019 02:15:41 -0500 Original-Received: from [176.228.60.248] (port=3955 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iTKyC-0005EN-LB; Sat, 09 Nov 2019 02:15:41 -0500 In-reply-to: <2074.1573258177@tigger3.sg.gildea.net> (message from Stephen Gildea on Fri, 08 Nov 2019 16:09:37 -0800) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:171301 Archived-At: > From: Stephen Gildea > cc: 32931@debbugs.gnu.org, jidanni@jidanni.org, rpluim@gmail.com > Date: Fri, 08 Nov 2019 16:09:37 -0800 > > Eli, I would like to introduce this feature to time-stamp the same way > I have introduced other features: implement first, document later. > Implement in this release, document in a later release. > > For example, the conversion "%q" (unqualified hostname) will be > new in Emacs 27. It is newly described in the doc string of > time-stamp-format. It is mentioned in 27.1 NEWS. But the only > new thing is the documentation; a key point is that the feature > works in Emacs 26, too. You can try it now: > (progn (require 'time-stamp) (time-stamp-string "%q")) I think it's bad for us to have undocumented features. We should have documented %q in Emacs 26. Why didn't we? And what happens if between the implementation release and the documentation release you change your interests and stop working on this? Who will remember that these features are implemented, but not documented? Finally, we have bug reports that complain about undocumented features, or documentation that seemingly contradicts the code. Are you subscribed to bug-gnu-emacs and intend to take care of such bug reports regarding the code you write in a timely fashion (read: before I or someone else invests time and energy into investigating the situation)? IOW, I have my gray hair from code that was installed without documentation to accompany it, for whatever reasons. I'd therefore like to minimize such situations, ideally to avoid them completely. > So why all this care with the timing of the time-stamp documentation? It isn't specific to time-stamp in any way. It's a general concern about our documentation being complete and up to date at any given point in time. We don't have dedicated people taking care of the documentation, and our own efforts to add documentation post factum proved in the past to be of insufficient quality. > Compatibility is difficult for time-stamp because people can set > time-stamp-pattern/time-stamp-format in their files. This captures > the current protocol, and these user files have to be considered when > making any change to the time-stamp implementation or documentation. > When someone sets time-stamp-pattern/time-stamp-format as a local > variable, they are relying on a promise that the next time Emacs > (any Emacs) reads that file, the setting will be honored still. > > Imagine that I don't do it this way, and a user sees a new feature. > (Perhaps the new feature is accompanied by a compatibility warning, but > the user thinks, "I use only my laptop, which I just upgraded to Emacs > 27.1, so this is okay.") They use the new feature in a local-variable > setting in their files. Time passes, and they forget they have used > this new feature. They give the file to a friend, or they edit it > from their work laptop, or they distribute the file on their git > repository. By one of these paths, the file ends up getting edited > with a different Emacs, say version 24.5. When that old Emacs saves > the file, it gets corrupted. I understand how changing the code can get users into these situations, but I fail to understand how documentation can have anything with them. What did I miss? > Given all the above, are you sure we want to document this now? I think so, yes. Unless I'm missing something important.