Improve time zone documentation

* doc/lispref/os.texi (Time Zone Rules):
New section, mostly with material moved here from other sections.
* doc/emacs/cmdargs.texi (General Variables):
* doc/lispref/os.texi (Time Conversion, Time Parsing):
Xref new section.
* etc/NEWS, etc/PROBLEMS:
* lisp/org/org.el (org-timestamp-format):
* src/editfns.c (Fformat_time_string, Fdecode_time)
(Fencode_time, Fcurrent_time_string, Fcurrent_time_zone)
(Fset_time_zone_rule):
When documenting time zone rule strings, mention the TZ
environment variable in preference to mentioning the
sort-of-internal function set-time-zone-rule.

1 files changed, 15 insertions, 12 deletions

diff --git a/src/editfns.c b/src/editfns.c
index 2ac0537eddb..94b949583ad 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1969,10 +1969,10 @@ DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0,
        doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted.
 TIME is specified as (HIGH LOW USEC PSEC), as returned by
 `current-time' or `file-attributes'.  The obsolete form (HIGH . LOW)
-is also still accepted.
-The optional ZONE is omitted or nil for Emacs local time, t for
-Universal Time, `wall' for system wall clock time, or a string as in
-`set-time-zone-rule' for a time zone rule.
+is also still accepted.  The optional ZONE is omitted or nil for Emacs
+local time, t for Universal Time, `wall' for system wall clock time,
+or a string as in the TZ environment variable.
+
 The value is a copy of FORMAT-STRING, but with certain constructs replaced
 by text that describes the specified date and time in TIME:
 
@@ -2086,7 +2086,7 @@ as from `current-time' and `file-attributes', or nil to use the
 current time.  The obsolete form (HIGH . LOW) is also still accepted.
 The optional ZONE is omitted or nil for Emacs local time, t for
 Universal Time, `wall' for system wall clock time, or a string as in
-`set-time-zone-rule' for a time zone rule.
+the TZ environment variable.
 
 The list has the following nine members: SEC is an integer between 0
 and 60; SEC is 60 for a leap second, which only some operating systems
@@ -2151,9 +2151,9 @@ DEFUN ("encode-time", Fencode_time, Sencode_time, 6, MANY, 0,
 This is the reverse operation of `decode-time', which see.
 The optional ZONE is omitted or nil for Emacs local time, t for
 Universal Time, `wall' for system wall clock time, or a string as in
-`set-time-zone-rule' for a time zone rule.  It can also be a list (as
-from `current-time-zone') or an integer (as from `decode-time')
-applied without consideration for daylight saving time.
+the TZ environment variable.  It can also be a list (as from
+`current-time-zone') or an integer (as from `decode-time') applied
+without consideration for daylight saving time.
 
 You can pass more than 7 arguments; then the first six arguments
 are used as SECOND through YEAR, and the *last* argument is used as ZONE.
@@ -2213,7 +2213,7 @@ but this is considered obsolete.
 
 The optional ZONE is omitted or nil for Emacs local time, t for
 Universal Time, `wall' for system wall clock time, or a string as in
-`set-time-zone-rule' for a time zone rule.  */)
+the TZ environment variable.  */)
   (Lisp_Object specified_time, Lisp_Object zone)
 {
   time_t value = lisp_seconds_argument (specified_time);
@@ -2290,7 +2290,7 @@ instead of using the current time.  The argument should have the form
 `current-time' and from `file-attributes'.  SPECIFIED-TIME can also
 have the form (HIGH . LOW), but this is considered obsolete.
 Optional second arg ZONE is omitted or nil for the local time zone, or
-a string as in `set-time-zone-rule'.
+a string as in the TZ environment variable.
 
 Some operating systems cannot provide all this information to Emacs;
 in this case, `current-time-zone' returns a list containing nil for
@@ -2331,8 +2331,11 @@ the data it can't find.  */)
 
 DEFUN ("set-time-zone-rule", Fset_time_zone_rule, Sset_time_zone_rule, 1, 1, 0,
        doc: /* Set the Emacs local time zone using TZ, a string specifying a time zone rule.
-If TZ is nil or `wall', use system wall clock time.  If TZ is t, use
-Universal Time.  If TZ is an integer, treat it as in `encode-time'.
+
+If TZ is nil or `wall', use system wall clock time; this differs from
+the usual Emacs convention where nil means current local time.  If TZ
+is t, use Universal Time.  If TZ is an integer, treat it as in
+`encode-time'.
 
 Instead of calling this function, you typically want something else.
 To temporarily use a different time zone rule for just one invocation