(date invocation): Use an example that makes it

clear tha the default date use space-padded day of month.
Replace "directive" with "conversion specifier" to be consistent
with POSIX.  All uses changed.
Fix menu RHS to match actual directive lists.
(Time conversion specifiers): Renamed from Time directives.
Use @samp consistently, sometimes instead of @code.
Consistently ention which specifiers are GNU extensions.
Give more examples (in some cases, instead of ranges).
Say why %F is preferred for dates.
(Date conversion specifiers): Renamed from Date directives.
Likewise for other changes.
(Padding and other flags): Correct the description.
Document #.  Give an example for %9B.

1 files changed, 111 insertions, 91 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f235fb2a0..57bc4c7dc 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -395,13 +395,13 @@ System context
 
 @command{date}: Print or set system date and time
 
-* Time directives::              Time directives
-* Date directives::              Date directives
-* Literal directives::           Literal directives
-* 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}
+* Time conversion specifiers::   %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::   %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers:: %[%nt]
+* 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.
 
 Modified command invocation
 
@@ -11417,7 +11417,7 @@ date [-u|--utc|--universal] @c this avoids a newline in the output
 Invoking @command{date} with no @var{format} argument is equivalent to invoking
 it with a default format that depends on the @env{LC_TIME} locale category.
 In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
-so the output looks like @samp{Fri Feb 27 13:47:51 PST 2004}.
+so the output looks like @samp{Thu Mar @ 3 13:47:51 PST 2005}.
 
 @vindex TZ
 Normally, @command{date} uses the time zone rules indicated by the
@@ -11432,165 +11432,179 @@ If given an argument that starts with a @samp{+}, @command{date} prints the
 current time and date (or the time and date specified by the
 @option{--date} option, see below) in the format defined by that argument,
 which is similar to that of the @code{strftime} function.  Except for
-directives, which start with @samp{%}, characters in the format string
-are printed unchanged.  The directives are described below.
+conversion specifiers, which start with @samp{%}, characters in the
+format string are printed unchanged.  The conversion specifiers are
+described below.
 
 @exitstatus
 
 @menu
-* Time directives::             %[HIklMprsSTXzZ]
-* Date directives::             %[aAbBcCdDhjmUwWxyY]
-* Literal directives::          %[%nt]
-* 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.
+* Time conversion specifiers::     %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::     %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers::  %[%nt]
+* 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.
 @end menu
 
-@node Time directives
-@subsection Time directives
+@node Time conversion specifiers
+@subsection Time conversion specifiers
 
-@cindex time directives
-@cindex directives, time
+@cindex time conversion specifiers
+@cindex conversion specifiers, time
 
-@command{date} directives related to times.
+@command{date} conversion specifiers related to times.
 
 @table @samp
 @item %H
-hour (00@dots{}23)
+hour (@samp{00}@dots{}@samp{23})
 @item %I
-hour (01@dots{}12)
+hour (@samp{01}@dots{}@samp{12})
 @item %k
-hour ( 0@dots{}23).
+hour (@samp{ 0}@dots{}@samp{23}).
 This is a @acronym{GNU} extension.
 @item %l
-hour ( 1@dots{}12).
+hour (@samp{ 1}@dots{}@samp{12}).
 This is a @acronym{GNU} extension.
 @item %M
-minute (00@dots{}59)
+minute (@samp{00}@dots{}@samp{59})
 @item %N
-nanoseconds (000000000@dots{}999999999)
+nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
+This is a @acronym{GNU} extension.
 @item %p
-locale's upper case @samp{AM} or @samp{PM} (blank in many locales).
+locale's equivalent of either @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).
-Noon is treated as @samp{pm} and midnight as @samp{am}.
+like @samp{%p}, except lower case.
 This is a @acronym{GNU} extension.
 @item %r
-locale's 12-hour time (hh:mm:ss [AP]M)
+locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
 @item %R
-24-hour hour and minute.  Same as @code{%H:%M}.
+24-hour hour and minute.  Same as @samp{%H:%M}.
+This is a @acronym{GNU} extension.
 @item %s
 @cindex epoch, seconds since
 @cindex seconds since the epoch
 @cindex beginning of time
 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.
+This is a @acronym{GNU} extension.
 @item %S
-second (00@dots{}60).  This may be @samp{60} if leap seconds are supported.
+second (@samp{00}@dots{}@samp{60}).
+This may be @samp{60} if leap seconds are supported.
 @item %T
-24-hour hour, minute, and second.  Same as @code{%H:%M:%S}.
+24-hour hour, minute, and second.  Same as @samp{%H:%M:%S}.
 @item %X
-locale's time representation (hh:mm:ss)
+locale's time representation (e.g., @samp{23:13:48})
 @item %z
-@w{RFC 2822}/@w{ISO 8601} style numeric time zone (e.g., @samp{-0600}
+@w{RFC 2822/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.
+This is a @acronym{GNU} extension.
 @item %Z
 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
 
 
-@node Date directives
-@subsection Date directives
+@node Date conversion specifiers
+@subsection Date conversion specifiers
 
-@cindex date directives
-@cindex directives, date
+@cindex date conversion specifiers
+@cindex conversion specifiers, date
 
-@command{date} directives related to dates.
+@command{date} conversion specifiers related to dates.
 
 @table @samp
 @item %a
-locale's abbreviated weekday name (Sun@dots{}Sat)
+locale's abbreviated weekday name (e.g., @samp{Sun})
 @item %A
-locale's full weekday name, variable length (Sunday@dots{}Saturday)
+locale's full weekday name, variable length (e.g., @samp{Sunday})
 @item %b
-locale's abbreviated month name (Jan@dots{}Dec)
+locale's abbreviated month name (e.g., @samp{Jan})
 @item %B
-locale's full month name, variable length (January@dots{}December)
+locale's full month name, variable length (e.g., @samp{January})
 @item %c
-locale's date and time (Sat Nov 04 12:02:33 EST 1989)
+locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2005})
 @item %C
-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}.
+century.  This is like @samp{%Y}, except the last two digits are omitted.
+For example, it is @samp{20} if @samp{%Y} is @samp{2000},
+and is @samp{-0} if @samp{%Y} is @samp{-001}.
 It is normally at least two characters, but it may be more.
 @item %d
-day of month (01@dots{}31)
+day of month (e.g., @samp{01})
 @item %D
-date (equivalent to @code{%m/%d/%y})
+date; same as @samp{%m/%d/%y}
 @item %e
-blank-padded day of month ( 1@dots{}31)
+day of month, space padded; same as @samp{%_d}
 @item %F
-the @w{ISO 8601} standard date format: @code{%Y-%m-%d}.
-This is the preferred form for all uses.
+full date in @w{ISO 8601} format; same as @samp{%Y-%m-%d}.
+This is a good choice for a date format, as it is standard and
+is easy to sort in the usual case where years are in the range
+0000@dots{}9999.
+This is a @acronym{GNU} extension.
 @item %g
 The year corresponding to the ISO week number, but without the century
-(range @code{00} through @code{99}).  This has the same format and value
-as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
+(range @samp{00} through @samp{99}).  This has the same format and value
+as @samp{%y}, except that if the ISO week number (see @samp{%V}) belongs
 to the previous or next year, that year is used instead.
+This is a @acronym{GNU} extension.
 @item %G
 The year corresponding to the ISO week number.  This has the same format
-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
+and value as @samp{%Y}, except that if the ISO week number (see
+@samp{%V}) belongs to the previous or next year, that year is used
 instead.
+This is a @acronym{GNU} extension.
 @item %h
-same as @code{%b}
+same as @samp{%b}
 @item %j
-day of year (001@dots{}366)
+day of year (@samp{001}@dots{}@samp{366})
 @item %m
-month (01@dots{}12)
+month (@samp{01}@dots{}@samp{12})
 @item %u
-day of week (1@dots{}7) with 1 corresponding to Monday
+day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
 @item %U
-week number of year with Sunday as first day of week (00@dots{}53).
+week number of year with Sunday as first day of week
+(@samp{00}@dots{}@samp{53}).
 Days in a new year preceding the first Sunday are in week zero.
 @item %V
 week number of year with Monday as first day of the week as a decimal
-(01@dots{}53).  If the week containing January 1 has four or more days in
+(@samp{01}@dots{}@samp{53}).
+If the week containing January 1 has four or more days in
 the new year, then it is considered week 1; otherwise, it is week 53 of
 the previous year, and the next week is week 1.  (See the @acronym{ISO} 8601
 standard.)
 @item %w
-day of week (0@dots{}6) with 0 corresponding to Sunday
+day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
 @item %W
-week number of year with Monday as first day of week (00@dots{}53).
+week number of year with Monday as first day of week
+(@samp{00}@dots{}@samp{53}).
 Days in a new year preceding the first Monday are in week zero.
 @item %x
-locale's date representation (mm/dd/yy)
+locale's date representation (e.g., @samp{12/31/99})
 @item %y
-last two digits of year (00@dots{}99)
+last two digits of year (@samp{00}@dots{}@samp{99})
 @item %Y
 year.  This is normally at least four characters, but it may be more.
-Year 0000 precedes year 0001, and year -001 precedes year 0000.
+Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
+precedes year @samp{0000}.
 @end table
 
 
-@node Literal directives
-@subsection Literal directives
+@node Literal conversion specifiers
+@subsection Literal conversion specifiers
 
-@cindex literal directives
-@cindex directives, literal
+@cindex literal conversion specifiers
+@cindex conversion specifiers, literal
 
-@command{date} directives that produce literal strings.
+@command{date} conversion specifiers that produce literal strings.
 
 @table @samp
 @item %%
@@ -11609,25 +11623,30 @@ a horizontal tab
 @cindex padding of numeric fields
 @cindex fields, padding numeric
 
-By default, @command{date} pads numeric fields with zeroes, so that, for
+Unless otherwise specified, @command{date} normally pads numeric fields
+with zeroes, so that, for
 example, numeric months are always output as two digits.
-Numbers that do not have a range are never
-padded, since there is no natural width for them.
+Seconds since the epoch are not padded, though,
+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 -
-(hyphen) do not pad the field; useful if the output is intended for
+(hyphen) Do not pad the field; useful if the output is intended for
 human consumption.
 @item _
-(underscore) pad the field with spaces; useful if you need a fixed
+(underscore) Pad 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.
+(zero) Pad with zeros even if the conversion specifier
+would normally pad with spaces.
 @item ^
 Use upper case characters if possible.
+@item #
+Use opposite case characters if possible.
+A field that is normally upper case becomes lower case, and vice versa.
 @end table
 
 @noindent
@@ -11643,25 +11662,26 @@ date +%_d/%_m -d "Feb 1"
 @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
+(after any flag, if present) 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.
+the result is written right adjusted and padded to the given
+size.  For example, @samp{%9B} prints the right adjusted month name in
+a field of width 9.
 
 An optional modifier can follow the optional flag and width
 specification.  The modifiers are:
 
-@table @code
+@table @samp
 @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
+modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
+@samp{%y} and @samp{%Y} conversion specifiers.  In a Japanese locale, for
+example, @samp{%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.
+applies only to numeric conversion specifiers.
 @end table
 
 If the format supports the modifier but no alternate representation
@@ -11878,7 +11898,7 @@ 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 (@acronym{GNU} extension)
-@code{-} flag to suppress
+@samp{-} flag to suppress
 the padding altogether:
 
 @example