(Time directives): Say that %k, %l, and %P are

GNU extensions.
For %p and %P, mention handling of noon and midnight.
For %s, use ISO 8601, and mention handling of leap seconds.
For %S, clarify mention of leap seconds.
For %T, say that it's the same as %H:%M:%S.
For %X, don't say that it must be the same as %H:%M:%S.
For %z and %Z, clarify which time zones are used.  These options
are now affected by --date, so don't claim that they're not.
(Date directives): %C is now all but the last two chars of %Y.
For %D, say that it's equivalent to %m/%d/%y.
For %e, use blank in example.
For %h, use @code for %b.
For %Y, mention what happens with outlandish years.
(Padding and other flags): Renamed from Padding.
Mention that the flags are GNU extensions.
Mention the 0 and ^ flags.
Mention field widths an modifiers.
(Examples of date): - is a flag, not a modifier.

1 files changed, 78 insertions, 37 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f1483fcfd..f235fb2a0 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -398,7 +398,7 @@ System context
 * Time directives::              Time directives
 * Date directives::              Date directives
 * Literal directives::           Literal directives
-* Padding::                      Padding
+* Padding and other flags::      Padding and other flags
 * Setting the time::             Setting the time
 * Options for date::             Options for @command{date}
 * Examples of date::             Examples of @command{date}
@@ -11441,7 +11441,7 @@ are printed unchanged.  The directives are described below.
 * Time directives::             %[HIklMprsSTXzZ]
 * Date directives::             %[aAbBcCdDhjmUwWxyY]
 * Literal directives::          %[%nt]
-* Padding::                     Pad with zeroes, spaces (%_), or nothing (%-).
+* Padding and other flags::     Pad with zeroes, spaces (%_), etc.
 * Setting the time::            Changing the system clock.
 * Options for date::            Instead of the current time.
 * Examples of date::            Examples.
@@ -11461,44 +11461,51 @@ hour (00@dots{}23)
 @item %I
 hour (01@dots{}12)
 @item %k
-hour ( 0@dots{}23)
+hour ( 0@dots{}23).
+This is a @acronym{GNU} extension.
 @item %l
-hour ( 1@dots{}12)
+hour ( 1@dots{}12).
+This is a @acronym{GNU} extension.
 @item %M
 minute (00@dots{}59)
 @item %N
 nanoseconds (000000000@dots{}999999999)
 @item %p
-locale's upper case @samp{AM} or @samp{PM} (blank in many locales)
+locale's upper case @samp{AM} or @samp{PM} (blank in many locales).
+Noon is treated as @samp{PM} and midnight as @samp{AM}.
 @item %P
-locale's lower case @samp{am} or @samp{pm} (blank in many locales)
+locale's lower case @samp{am} or @samp{pm} (blank in many locales).
+Noon is treated as @samp{pm} and midnight as @samp{am}.
+This is a @acronym{GNU} extension.
 @item %r
-time, 12-hour (hh:mm:ss [AP]M)
+locale's 12-hour time (hh:mm:ss [AP]M)
 @item %R
-time, 24-hour (hh:mm).  Same as @code{%H:%M}.
+24-hour hour and minute.  Same as @code{%H:%M}.
 @item %s
 @cindex epoch, seconds since
 @cindex seconds since the epoch
 @cindex beginning of time
-seconds since the epoch, i.e., 1 January 1970 00:00:00 UTC (a GNU extension).
-For examples, @xref{%s-examples}.
+seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
+Leap seconds are not counted unless leap second support is available.
+This is a @acronym{GNU} extension.
+@xref{%s-examples}, for examples.
 @item %S
-second (00@dots{}60).  The range is [00@dots{}60], and not [00@dots{}59],
-in order to accommodate the occasional positive leap second.
+second (00@dots{}60).  This may be @samp{60} if leap seconds are supported.
 @item %T
-time, 24-hour (hh:mm:ss)
+24-hour hour, minute, and second.  Same as @code{%H:%M:%S}.
 @item %X
-locale's time representation (%H:%M:%S)
+locale's time representation (hh:mm:ss)
 @item %z
-RFC-2822 style numeric time zone (e.g., @samp{-0600} or @samp{+0100}),
-or nothing if no
-time zone is determinable.  This value reflects the @emph{current} time
-zone.  It isn't changed by the @option{--date} option.
+@w{RFC 2822}/@w{ISO 8601} style numeric time zone (e.g., @samp{-0600}
+or @samp{+0100}), or nothing if no
+time zone is determinable.  This value reflects the numeric time zone
+appropriate for the current time, using the time zone rules specified
+by the @env{TZ} environment variable.
+The time (and optionally, the time zone rules) can be overridden
+by the @option{--date} option.
 @item %Z
-time zone (e.g., EDT), or nothing if no time zone is
-determinable.
-Note that this value reflects the @emph{current} time zone.
-It isn't changed by the @option{--date} option.
+alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
+time zone is determinable.  See @samp{%z} for how it is determined.
 @end table
 
 
@@ -11522,13 +11529,16 @@ locale's full month name, variable length (January@dots{}December)
 @item %c
 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
 @item %C
-century (year divided by 100 and truncated to an integer) (00@dots{}99)
+century.  This is like @code{%Y}, except the last two digits are omitted.
+For example, it is @samp{20} if @code{%Y} is @samp{2000},
+and is @samp{-0} if @code{%Y} is @samp{-001}.
+It is normally at least two characters, but it may be more.
 @item %d
 day of month (01@dots{}31)
 @item %D
-date (mm/dd/yy)
+date (equivalent to @code{%m/%d/%y})
 @item %e
-blank-padded day of month (1@dots{}31)
+blank-padded day of month ( 1@dots{}31)
 @item %F
 the @w{ISO 8601} standard date format: @code{%Y-%m-%d}.
 This is the preferred form for all uses.
@@ -11543,7 +11553,7 @@ and value as @code{%Y}, except that if the ISO week number (see
 @code{%V}) belongs to the previous or next year, that year is used
 instead.
 @item %h
-same as %b
+same as @code{%b}
 @item %j
 day of year (001@dots{}366)
 @item %m
@@ -11569,7 +11579,8 @@ locale's date representation (mm/dd/yy)
 @item %y
 last two digits of year (00@dots{}99)
 @item %Y
-year (1970@dots{}.)
+year.  This is normally at least four characters, but it may be more.
+Year 0000 precedes year 0001, and year -001 precedes year 0000.
 @end table
 
 
@@ -11591,8 +11602,8 @@ a horizontal tab
 @end table
 
 
-@node Padding
-@subsection Padding
+@node Padding and other flags
+@subsection Padding and other flags
 
 @cindex numeric field padding
 @cindex padding of numeric fields
@@ -11600,9 +11611,11 @@ a horizontal tab
 
 By default, @command{date} pads numeric fields with zeroes, so that, for
 example, numeric months are always output as two digits.
-@acronym{GNU} @command{date}
-recognizes the following numeric modifiers between the @samp{%} and the
-directive.
+Numbers that do not have a range are never
+padded, since there is no natural width for them.
+
+As a @acronym{GNU} extension, @command{date} recognizes any of the
+following optional flags after the @samp{%}:
 
 @table @samp
 @item -
@@ -11611,12 +11624,14 @@ human consumption.
 @item _
 (underscore) pad the field with spaces; useful if you need a fixed
 number of characters in the output, but zeroes are too distracting.
+@item 0
+(zero) Pad with zeros even if the format specifies padding with spaces.
+@item ^
+Use upper case characters if possible.
 @end table
 
 @noindent
-These are GNU extensions.
-
-Here is an example illustrating the differences:
+Here are some examples of padding:
 
 @example
 date +%d/%m -d "Feb 1"
@@ -11627,6 +11642,31 @@ date +%_d/%_m -d "Feb 1"
 @result{}  1/ 2
 @end example
 
+As a @acronym{GNU} extension, you can specify the field width
+after any flag, as a decimal number.  If the natural size of the
+output is of the field has less than the specified number of characters,
+the result is written right adjusted and space padded to the given
+size.
+
+An optional modifier can follow the optional flag and width
+specification.  The modifiers are:
+
+@table @code
+@item E
+Use the locale's alternate representation for date and time.  This
+modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X},
+@code{%y} and @code{%Y} format specifiers.  In a Japanese locale, for
+example, @code{%Ex} might yield a date format based on the Japanese
+Emperors' reigns.
+
+@item O
+Use the locale's alternate numeric symbols for numbers.  This modifier
+applies only to numeric format specifiers.
+@end table
+
+If the format supports the modifier but no alternate representation
+is available, it is ignored.
+
 
 @node Setting the time
 @subsection Setting the time
@@ -11837,7 +11877,8 @@ for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
 
 @item
 To print a date without the leading zero for one-digit days
-of the month, you can use the (GNU extension) @code{-} modifier to suppress
+of the month, you can use the (@acronym{GNU} extension)
+@code{-} flag to suppress
 the padding altogether:
 
 @example
@@ -11846,7 +11887,7 @@ date -d 1may '+%B %-d
 
 @item
 To print the current date and time in the format required by many
-non-GNU versions of @command{date} when setting the system clock:
+non-@acronym{GNU} versions of @command{date} when setting the system clock:
 
 @example
 date +%m%d%H%M%Y.%S