[Emacs-diffs] master 870c56a 3/3: Merge from origin/emacs-25

[Paul Eggert]

branch: master
commit 870c56a0bd8fe51baa2efa20a75b848f2bd27fd4
Merge: 6a03b47 07f45d7
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    Merge from origin/emacs-25
    
    07f45d7 ; Spelling fix
    1a210f0 * admin/release-process: Update versions and blocking bug num...
    36bafc9 Improve documentation of functions that accept time values
    
    # Conflicts:
    #   admin/release-process
    #   src/editfns.c
---
 admin/release-process |    9 ++++-----
 doc/lispref/os.texi   |   13 +++++++++----
 nt/README.W32         |    2 +-
 src/editfns.c         |   33 ++++++++++++++++++++++-----------
 4 files changed, 36 insertions(+), 21 deletions(-)

diff --git a/admin/release-process b/admin/release-process
index 28f2307..6aa0040 100644
--- a/admin/release-process
+++ b/admin/release-process
@@ -46,13 +46,12 @@ See admin/gitmerge.el.
 Emacs uses the "blocking" feature of Debbugs for bugs that need to be
 addressed in the next release.
 
-Currently, bug#19759 is the tracking bug for release of 25.1 and
-bug#21966 is the tracking bug for release of 25.2.  Say bug#123 needs
-bug#21966 is the tracking bug for the next release.  Say bug#123 needs
-to be fixed for Emacs 25.1.  Send a message to address@hidden
+Currently, bug#21966 is the tracking bug for release of 25.2 and
+bug#24655 is the tracking bug for release 26.1.  Say bug#123 needs
+to be fixed for Emacs 26.1.  Send a message to address@hidden
 that says:
 
-   block 19759 by 123
+   block 24655 by 123
 
 Change "block" to "unblock" to remove a bug from the list.  Closed
 bugs are not listed as blockers, so you do not need to explicitly
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 903bad3..616d1e7 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1474,7 +1474,7 @@ corresponding time value.
 @defun format-time-string format-string &optional time zone
 
 This function converts @var{time} (or the current time, if
address@hidden is omitted) to a string according to
address@hidden is omitted or @code{nil}) to a string according to
 @var{format-string}.  The conversion uses the time zone rule @var{zone}, which
 defaults to the current time zone rule.  @xref{Time Zone Rules}.  The argument
 @var{format-string} may contain @samp{%}-sequences which say to
@@ -1692,7 +1692,9 @@ interactively, it prints the duration in the echo area.
 @cindex calendrical computations
 
   These functions perform calendrical computations using time values
-(@pxref{Time of Day}).
+(@pxref{Time of Day}).  A value of @code{nil} for any of their
+time-value arguments stands for the current system time, and a single
+integer number stands for the number of seconds since the epoch.
 
 @defun time-less-p t1 t2
 This returns @code{t} if time value @var{t1} is less than time value
@@ -1701,12 +1703,15 @@ This returns @code{t} if time value @var{t1} is less 
than time value
 
 @defun time-subtract t1 t2
 This returns the time difference @var{t1} @minus{} @var{t2} between
-two time values, as a time value.
+two time values, as a time value.  If you need the difference in units
+of elapsed seconds, use @code{float-time} (@pxref{Time of Day,
+float-time}) to convert the result into seconds.
 @end defun
 
 @defun time-add t1 t2
 This returns the sum of two time values, as a time value.
-One argument should represent a time difference rather than a point in time.
+One argument should represent a time difference rather than a point in time,
+either as a list or as a single number of elapsed seconds.
 Here is how to add a number of seconds to a time value:
 
 @example
diff --git a/nt/README.W32 b/nt/README.W32
index b65a1de..9bc8f87 100644
--- a/nt/README.W32
+++ b/nt/README.W32
@@ -283,7 +283,7 @@ See the end of the file for license conditions.
   To ask questions on this mailing list, send email to
   address@hidden
 
-  A mailing list for issuesspecifically related to the MS-Windows port
+  A mailing list for issues specifically related to the MS-Windows port
   of Emacs is here:
 
        http://lists.gnu.org/mailman/listinfo/help-emacs-windows
diff --git a/src/editfns.c b/src/editfns.c
index 4f61081..70c5383 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1609,21 +1609,28 @@ time_arith (Lisp_Object a, Lisp_Object b,
 }
 
 DEFUN ("time-add", Ftime_add, Stime_add, 2, 2, 0,
-       doc: /* Return the sum of two time values A and B, as a time value.  */)
+       doc: /* Return the sum of two time values A and B, as a time value.
+A nil value for either argument stands for the current time.
+See `current-time-string' for the various forms of a time value.  */)
   (Lisp_Object a, Lisp_Object b)
 {
   return time_arith (a, b, time_add);
 }
 
 DEFUN ("time-subtract", Ftime_subtract, Stime_subtract, 2, 2, 0,
-       doc: /* Return the difference between two time values A and B, as a 
time value.  */)
+       doc: /* Return the difference between two time values A and B, as a 
time value.
+Use `float-time' to convert the difference into elapsed seconds.
+A nil value for either argument stands for the current time.
+See `current-time-string' for the various forms of a time value.  */)
   (Lisp_Object a, Lisp_Object b)
 {
   return time_arith (a, b, time_subtract);
 }
 
 DEFUN ("time-less-p", Ftime_less_p, Stime_less_p, 2, 2, 0,
-       doc: /* Return non-nil if time value T1 is earlier than time value T2.  
*/)
+       doc: /* Return non-nil if time value T1 is earlier than time value T2.
+A nil value for either argument stands for the current time.
+See `current-time-string' for the various forms of a time value.  */)
   (Lisp_Object t1, Lisp_Object t2)
 {
   int t1len, t2len;
@@ -2001,10 +2008,11 @@ emacs_nmemftime (char *s, size_t maxsize, const char 
*format,
 }
 
 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.
+       doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted or 
nil.
 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.
+`current-time' or `file-attributes'.  It can also be a single integer
+number of seconds since the epoch.  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
@@ -2127,7 +2135,8 @@ DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 2, 0,
        doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST 
UTCOFF).
 The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED),
 as from `current-time' and `file-attributes', or nil to use the
-current time.  The obsolete form (HIGH . LOW) is also still accepted.
+current time.  It can also be a single integer number of seconds since
+the epoch.  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
@@ -2253,8 +2262,9 @@ which provide a much more powerful and general facility.
 If SPECIFIED-TIME is given, it is a time to format instead of the
 current time.  The argument should have the form (HIGH LOW . IGNORED).
 Thus, you can use times obtained from `current-time' and from
-`file-attributes'.  SPECIFIED-TIME can also have the form (HIGH . LOW),
-but this is considered obsolete.
+`file-attributes'.  SPECIFIED-TIME can also be a single integer number
+of seconds since the epoch.  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
@@ -2334,8 +2344,9 @@ NAME is a string giving the name of the time zone.
 If SPECIFIED-TIME is given, the time zone offset is determined from it
 instead of using the current time.  The argument should have the form
 \(HIGH LOW . IGNORED).  Thus, you can use times obtained from
-`current-time' and from `file-attributes'.  SPECIFIED-TIME can also
-have the form (HIGH . LOW), but this is considered obsolete.
+`current-time' and from `file-attributes'.  SPECIFIED-TIME can also be
+a single integer number of seconds since the epoch.  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