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.

2 files changed, 33 insertions, 15 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 59c269a3084..0cb9de9f9a8 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}.
+@item %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
+@samp{-0500}, 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
+@samp{-05} in the same example.
+@item %%
+This stands for a single @samp{%}.
 @end table
 
+One or more flag characters can appear immediately after the @samp{%}.
+@samp{0} 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
-@samp{%} 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
+@samp{%}-sequences 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 e65bd34da87..f6f5ccc9480 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,