[Emacs-diffs] emacs-26 8ca6fa5: Improve format-time-string doc

[Paul Eggert]

branch: emacs-26
commit 8ca6fa585add53db66fb17b151e67029d68cc9ef
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    Improve format-time-string doc
    
    * doc/lispref/os.texi (Time Parsing): Fix some errors in the
    documentation for format-time-string.  Document ^, #, %s, and %z
    with colons.  Say that unrecognized sequences are output as-is.
    * src/editfns.c (Fformat_time_string): %S can stand for 60.
    Also mention unrecognized sequences.
---
 doc/lispref/os.texi | 37 +++++++++++++++++++++++++++----------
 src/editfns.c       | 11 ++++++-----
 2 files changed, 33 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 59c269a..0cb9de9 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1486,8 +1486,8 @@ This stands for the full name of the month.
 @item %c
 This is a synonym for @samp{%x %X}.
 @item %C
-This has a locale-specific meaning.  In the default locale (named C), it
-is equivalent to @samp{%A, %B %e, %Y}.
+This stands for the century, that is, the year divided by 100,
+truncated toward zero.
 @item %d
 This stands for the day of month, zero-padded.
 @item %D
@@ -1530,8 +1530,11 @@ This stands for the calendar quarter (1--4).
 This is a synonym for @samp{%I:%M:%S %p}.
 @item %R
 This is a synonym for @samp{%H:%M}.
address@hidden %s
+This stands for the integer number of seconds since the epoch.
 @item %S
-This stands for the seconds (00--59).
+This stands for the second (00--59, or 00--60 on platforms
+that support leap seconds).
 @item %t
 This stands for a tab character.
 @item %T
@@ -1561,22 +1564,31 @@ This stands for the year with century.
 @item %Z
 This stands for the time zone abbreviation (e.g., @samp{EST}).
 @item %z
-This stands for the time zone numerical offset (e.g., @samp{-0500}).
+This stands for the time zone numerical offset.  The @samp{z} can be
+preceded by one, two, or three colons; if plain @samp{%z} stands for
address@hidden, then @samp{%:z} stands for @samp{-05:00}, @samp{%::z}
+stands for @samp{-05:00:00}, and @samp{%:::z} is like @samp{%::z}
+except it suppresses trailing instances of @samp{:00} so it stands for
address@hidden in the same example.
address@hidden %%
+This stands for a single @samp{%}.
 @end table
 
+One or more flag characters can appear immediately after the @samp{%}.
address@hidden pads with zeros, @samp{_} pads with blanks, @samp{-}
+suppresses padding, @samp{^} upper-cases letters, and @samp{#}
+reverses the case of letters.
+
 You can also specify the field width and type of padding for any of
 these @samp{%}-sequences.  This works as in @code{printf}: you write
-the field width as digits in the middle of a @samp{%}-sequences.  If you
-start the field width with @samp{0}, it means to pad with zeros.  If you
-start the field width with @samp{_}, it means to pad with spaces.
-
+the field width as digits in a @samp{%}-sequence, after any flags.
 For example, @samp{%S} specifies the number of seconds since the minute;
 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
 pad with spaces to 3 positions.  Plain @samp{%3S} pads with zeros,
 because that is how @samp{%S} normally pads to two positions.
 
-The characters @samp{E} and @samp{O} act as modifiers when used between
address@hidden and one of the letters in the table above.  @samp{E} specifies
+The characters @samp{E} and @samp{O} act as modifiers when used after
+any flags and field widths in a @samp{%}-sequence.  @samp{E} specifies
 using the current locale's alternative version of the date and time.
 In a Japanese locale, for example, @code{%Ex} might yield a date format
 based on the Japanese Emperors' reigns.  @samp{E} is allowed in
@@ -1587,6 +1599,11 @@ based on the Japanese Emperors' reigns.  @samp{E} is 
allowed in
 representation of numbers, instead of the ordinary decimal digits.  This
 is allowed with most letters, all the ones that output numbers.
 
+To help debug programs, unrecognized @samp{%}-sequences stand for
+themselves and are output as-is.  Programs should not rely on this
+behavior, as future versions of Emacs may recognize new
address@hidden as extensions.
+
 This function uses the C library function @code{strftime}
 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
 Manual}) to do most of the work.  In order to communicate with that
diff --git a/src/editfns.c b/src/editfns.c
index e65bd34..f6f5ccc 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2038,11 +2038,11 @@ by text that describes the specified date and time in 
TIME:
  only blank-padded, %l is like %I blank-padded.
 %p is the locale's equivalent of either AM or PM.
 %q is the calendar quarter (1–4).
-%M is the minute.
-%S is the second.
-%N is the nanosecond, %6N the microsecond, %3N the millisecond, etc.
-%Z is the time zone name, %z is the numeric form.
+%M is the minute (00-59).
+%S is the second (00-59; 00-60 on platforms with leap seconds)
 %s is the number of seconds since 1970-01-01 00:00:00 +0000.
+%N is the nanosecond, %6N the microsecond, %3N the millisecond, etc.
+%Z is the time zone abbreviation, %z is the numeric form.
 
 %c is the locale's date and time format.
 %x is the locale's "preferred" date format.
@@ -2052,7 +2052,8 @@ by text that describes the specified date and time in 
TIME:
 %R is like "%H:%M", %T is like "%H:%M:%S", %r is like "%I:%M:%S %p".
 %X is the locale's "preferred" time format.
 
-Finally, %n is a newline, %t is a tab, %% is a literal %.
+Finally, %n is a newline, %t is a tab, %% is a literal %, and
+unrecognized %-sequences stand for themselves.
 
 Certain flags and modifiers are available with some format controls.
 The flags are `_', `-', `^' and `#'.  For certain characters X,