Re: date --help sends one digging RFCs

[Paul Eggert]

Eric Blake <address@hidden> writes:

> 2005-02-26  Eric Blake  <address@hidden>
>
>       * coreutils.texi (Padding and other flags): Mention # flag.

Thanks for mentioning the problem.  I went through the source and
documentation with a fine-toothed comb, compared them to what POSIX
specifieds, and installed the following changes.

Not that this addresses the original complaint.  Date's usage strings
should be brief, and I couldn't see any way to explain it the way that
he preferred without becoming either more confusing or too prolix (or
both).

2005-03-08  Paul Eggert  <address@hidden>

        * doc/coreutils.texi (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.

        * src/date.c (usage): Redo to match recent documentation changes.
        Don't bother documenting which usages are GNU extensions; the list
        wasn't correct, and is better left to the printed manual anyway.

Index: doc/coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.242
diff -p -u -r1.242 coreutils.texi
--- doc/coreutils.texi  24 Feb 2005 00:27:44 -0000      1.242
+++ doc/coreutils.texi  8 Mar 2005 22:18:55 -0000
@@ -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 avoi
 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 
 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
 
address@hidden Time directives
address@hidden Time directives
address@hidden Time conversion specifiers
address@hidden Time conversion specifiers
 
address@hidden time directives
address@hidden directives, time
address@hidden time conversion specifiers
address@hidden conversion specifiers, time
 
address@hidden directives related to times.
address@hidden conversion specifiers related to times.
 
 @table @samp
 @item %H
-hour (address@hidden)
+hour (@address@hidden@samp{23})
 @item %I
-hour (address@hidden)
+hour (@address@hidden@samp{12})
 @item %k
-hour ( address@hidden).
+hour (@samp{ address@hidden@samp{23}).
 This is a @acronym{GNU} extension.
 @item %l
-hour ( address@hidden).
+hour (@samp{ address@hidden@samp{12}).
 This is a @acronym{GNU} extension.
 @item %M
-minute (address@hidden)
+minute (@address@hidden@samp{59})
 @item %N
-nanoseconds (address@hidden)
+nanoseconds (@address@hidden@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 (address@hidden).  This may be @samp{60} if leap seconds are supported.
+second (@address@hidden@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
address@hidden 2822}/@w{ISO 8601} style numeric time zone (e.g., @samp{-0600}
address@hidden 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
 
 
address@hidden Date directives
address@hidden Date directives
address@hidden Date conversion specifiers
address@hidden Date conversion specifiers
 
address@hidden date directives
address@hidden directives, date
address@hidden date conversion specifiers
address@hidden conversion specifiers, date
 
address@hidden directives related to dates.
address@hidden conversion specifiers related to dates.
 
 @table @samp
 @item %a
-locale's abbreviated weekday name (address@hidden)
+locale's abbreviated weekday name (e.g., @samp{Sun})
 @item %A
-locale's full weekday name, variable length (address@hidden)
+locale's full weekday name, variable length (e.g., @samp{Sunday})
 @item %b
-locale's abbreviated month name (address@hidden)
+locale's abbreviated month name (e.g., @samp{Jan})
 @item %B
-locale's full month name, variable length (address@hidden)
+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 (address@hidden)
+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 ( address@hidden)
+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
address@hidden
+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
address@hidden) belongs to the previous or next year, that year is used
+and value as @samp{%Y}, except that if the ISO week number (see
address@hidden) 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 (address@hidden)
+day of year (@address@hidden@samp{366})
 @item %m
-month (address@hidden)
+month (@address@hidden@samp{12})
 @item %u
-day of week (address@hidden) with 1 corresponding to Monday
+day of week (@address@hidden@samp{7}) with @samp{1} corresponding to Monday
 @item %U
-week number of year with Sunday as first day of week (address@hidden).
+week number of year with Sunday as first day of week
+(@address@hidden@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
-(address@hidden).  If the week containing January 1 has four or more days in
+(@address@hidden@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 (address@hidden) with 0 corresponding to Sunday
+day of week (@address@hidden@samp{6}) with 0 corresponding to Sunday
 @item %W
-week number of year with Monday as first day of week (address@hidden).
+week number of year with Monday as first day of week
+(@address@hidden@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 (address@hidden)
+last two digits of year (@address@hidden@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
 
 
address@hidden Literal directives
address@hidden Literal directives
address@hidden Literal conversion specifiers
address@hidden Literal conversion specifiers
 
address@hidden literal directives
address@hidden directives, literal
address@hidden literal conversion specifiers
address@hidden conversion specifiers, literal
 
address@hidden directives that produce literal strings.
address@hidden 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.
address@hidden #
+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:
 
address@hidden @code
address@hidden @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},
address@hidden 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},
address@hidden 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'}
 @item
 To print a date without the leading zero for one-digit days
 of the month, you can use the (@acronym{GNU} extension)
address@hidden flag to suppress
address@hidden flag to suppress
 the padding altogether:
 
 @example
Index: src/date.c
===================================================================
RCS file: /fetish/cu/src/date.c,v
retrieving revision 1.140
diff -p -u -r1.140 date.c
--- src/date.c  21 Feb 2005 08:14:13 -0000      1.140
+++ src/date.c  8 Mar 2005 22:18:55 -0000
@@ -147,24 +147,24 @@ FORMAT controls the output.  The only va
 specifies Coordinated Universal Time.  Interpreted sequences are:\n\
 \n\
   %%   a literal %\n\
-  %a   locale's abbreviated weekday name (Sun..Sat)\n\
+  %a   locale's abbreviated weekday name (e.g., Sun)\n\
 "), stdout);
       fputs (_("\
-  %A   locale's full weekday name, variable length (Sunday..Saturday)\n\
-  %b   locale's abbreviated month name (Jan..Dec)\n\
-  %B   locale's full month name, variable length (January..December)\n\
-  %c   locale's date and time (Sat Nov 04 12:02:33 EST 1989)\n\
+  %A   locale's full weekday name (e.g., Sunday)\n\
+  %b   locale's abbreviated month name (e.g., Jan)\n\
+  %B   locale's full month name (e.g., January)\n\
+  %c   locale's date and time (e.g., Thu Mar  3 23:05:25 2005)\n\
 "), stdout);
       fputs (_("\
-  %C   century (year divided by 100 and truncated to an integer) [00-99]\n\
-  %d   day of month (01..31)\n\
-  %D   date (mm/dd/yy)\n\
-  %e   day of month, blank padded ( 1..31)\n\
+  %C   century; like %Y, except omit last two digits (e.g., 21)\n\
+  %d   day of month (e.g, 01)\n\
+  %D   date; same as %m/%d/%y\n\
+  %e   day of month, space padded; same as %_d\n\
 "), stdout);
       fputs (_("\
-  %F   same as %Y-%m-%d\n\
-  %g   the 2-digit year corresponding to the %V week number\n\
-  %G   the 4-digit year corresponding to the %V week number\n\
+  %F   full date; same as %Y-%m-%d\n\
+  %g   the last two digits of the year corresponding to the %V week number\n\
+  %G   the year corresponding to the %V week number\n\
 "), stdout);
       fputs (_("\
   %h   same as %b\n\
@@ -181,39 +181,49 @@ specifies Coordinated Universal Time.  I
       fputs (_("\
   %n   a newline\n\
   %N   nanoseconds (000000000..999999999)\n\
-  %p   locale's upper case AM or PM indicator (blank in many locales)\n\
-  %P   locale's lower case am or pm indicator (blank in many locales)\n\
-  %r   time, 12-hour (hh:mm:ss [AP]M)\n\
-  %R   time, 24-hour (hh:mm)\n\
-  %s   seconds since `00:00:00 1970-01-01 UTC' (a GNU extension)\n\
+  %p   locale's equivalent of either AM or PM; blank if not known\n\
+  %P   like %p, but lower case\n\
+  %r   locale's 12-hour clock time (e.g., 11:11:04 PM)\n\
+  %R   24-hour hour and minute; same as %H:%M\n\
+  %s   seconds since 1970-01-01 00:00:00 UTC\n\
 "), stdout);
       fputs (_("\
-  %S   second (00..60); the 60 is necessary to accommodate a leap second\n\
-  %t   a horizontal tab\n\
-  %T   time, 24-hour (hh:mm:ss)\n\
-  %u   day of week (1..7);  1 represents Monday\n\
+  %S   second (00..60)\n\
+  %t   a tab\n\
+  %T   time; same as %H:%M:%S\n\
+  %u   day of week (1..7); 1 is Monday\n\
 "), stdout);
       fputs (_("\
   %U   week number of year with Sunday as first day of week (00..53)\n\
   %V   week number of year with Monday as first day of week (01..53)\n\
-  %w   day of week (0..6);  0 represents Sunday\n\
+  %w   day of week (0..6); 0 is Sunday\n\
   %W   week number of year with Monday as first day of week (00..53)\n\
 "), stdout);
       fputs (_("\
-  %x   locale's date representation (mm/dd/yy)\n\
-  %X   locale's time representation (%H:%M:%S)\n\
+  %x   locale's date representation (e.g., 12/31/99)\n\
+  %X   locale's time representation (e.g., 23:13:48)\n\
   %y   last two digits of year (00..99)\n\
-  %Y   year (1970...)\n\
+  %Y   year\n\
 "), stdout);
       fputs (_("\
-  %z   RFC-2822 style numeric timezone (-0500) (a nonstandard extension)\n\
-  %Z   time zone (e.g., EDT), or nothing if no time zone is determinable\n\
+  %z   numeric timezone (e.g., -0400)\n\
+  %Z   alphabetic time zone abbreviation (e.g., EDT)\n\
 \n\
-By default, date pads numeric fields with zeroes.  GNU date recognizes\n\
-the following modifiers between `%' and a numeric directive.\n\
+By default, date pads numeric fields with zeroes.\n\
+The following optional flags may follow `%':\n\
 \n\
-  `-' (hyphen) do not pad the field\n\
-  `_' (underscore) pad the field with spaces\n\
+  - (hyphen) do not pad the field\n\
+  _ (underscore) pad with spaces\n\
+  0 (zero) pad with zeros\n\
+  ^ use upper case if possible\n\
+  # use opposite case if possible\n\
+"), stdout);
+      fputs (_("\
+\n\
+After any flags comes an optional field width, as a decimal number;\n\
+then an optional modifier, which is either\n\
+E to use the locale's alternate representations if available, or\n\
+O to use the locale's alternate numeric symbols if available.\n\
 "), stdout);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }