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.

1 files changed, 27 insertions, 10 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