bug#32931: time-stamp-format: offer numeric time zones too

[Eli Zaretskii <eliz@gnu.org>]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> 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.