Re: date --help sends one digging RFCs

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Dan Jacobson on 2/25/2005 4:18 PM:
> P> Consider that most people reading the docs will know the option exists
> P> and are simply confirming syntax, or won't care.
> 
> Well I think --help at least could cut to the chase with actual samples.
> 
> even that % stuff requires thinking.  --help is nice and informal
> place for the non thinkers.

Instead of complaining, why not propose a patch?  It doesn't even have to
be to the code, necessarily - just proposing what you want --help (and
thus the man page) to say is a good start.

Unfortunately, my proposed patch is probably big enough that it can't be
applied until I get my employer to sign the paperwork.

coreutils/doc/ChangeLog
2005-02-26  Eric Blake  <address@hidden>

        * coreutils.texi (Padding and other flags): Mention # flag.

coreutils/ChangeLog
2005-02-26  Eric Blake  <address@hidden>

        * src/date.c (usage): Update help text.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFCII3884KuGfSFAYARAq3hAKCq5GtdzM62oU04SwwtjQRLSejnJACfWqMe
rZOeJ3MUL3cdRuB9LU/hQEg=
=SL7G
-----END PGP SIGNATURE-----

Index: doc/coreutils.texi
===================================================================
RCS file: /cvsroot/coreutils/coreutils/doc/coreutils.texi,v
retrieving revision 1.242
diff -u -p -r1.242 coreutils.texi
--- doc/coreutils.texi  24 Feb 2005 00:27:44 -0000      1.242
+++ doc/coreutils.texi  26 Feb 2005 14:50:37 -0000
@@ -11628,6 +11628,10 @@ number of characters in the output, but 
 (zero) Pad with zeros even if the format specifies padding with spaces.
 @item ^
 Use upper case characters if possible.
address@hidden #
+Use opposite case characters if possible.  Fields that are normally upper
+case become lower case (pZ); fields that are normally lower case become
+upper case (aAbBh).
 @end table
 
 @noindent
Index: src/date.c
===================================================================
RCS file: /cvsroot/coreutils/coreutils/src/date.c,v
retrieving revision 1.140
diff -u -p -r1.140 date.c
--- src/date.c  21 Feb 2005 08:14:13 -0000      1.140
+++ src/date.c  26 Feb 2005 14:50:37 -0000
@@ -135,7 +135,8 @@ Display the current time in the given FO
 "), stdout);
       fputs (_("\
   -r, --reference=FILE      display the last modification time of FILE\n\
-  -R, --rfc-2822            output RFC-2822 compliant date string\n\
+  -R, --rfc-2822            output RFC-2822 compliant date string in the\n\
+                            C locale (%a, %d %b %Y %H:%M:%S %z)\n\
   -s, --set=STRING          set time described by STRING\n\
   -u, --utc, --universal    print or set Coordinated Universal Time\n\
 "), stdout);
@@ -144,7 +145,8 @@ Display the current time in the given FO
       fputs (_("\
 \n\
 FORMAT controls the output.  The only valid option for the second form\n\
-specifies Coordinated Universal Time.  Interpreted sequences are:\n\
+specifies Coordinated Universal Time.  Examples for locale-specific\n\
+sequences are drawn from the C locale.  Interpreted sequences are:\n\
 \n\
   %%   a literal %\n\
   %a   locale's abbreviated weekday name (Sun..Sat)\n\
@@ -156,41 +158,41 @@ specifies Coordinated Universal Time.  I
   %c   locale's date and time (Sat Nov 04 12:02:33 EST 1989)\n\
 "), stdout);
       fputs (_("\
-  %C   century (year divided by 100 and truncated to an integer) [00-99]\n\
+  %C   century, variable length; like %Y with last two digits omitted\n\
   %d   day of month (01..31)\n\
-  %D   date (mm/dd/yy)\n\
+  %D   date; same as %m/%d/%y\n\
   %e   day of month, blank padded ( 1..31)\n\
 "), stdout);
       fputs (_("\
-  %F   same as %Y-%m-%d\n\
+  %F   date; 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\
+  %G   the full year corresponding to the %V week number, >= 4 characters\n\
 "), stdout);
       fputs (_("\
-  %h   same as %b\n\
+  %h   month; same as %b\n\
   %H   hour (00..23)\n\
   %I   hour (01..12)\n\
   %j   day of year (001..366)\n\
 "), stdout);
       fputs (_("\
-  %k   hour ( 0..23)\n\
-  %l   hour ( 1..12)\n\
+  %k   hour ( 0..23) (a GNU extension)\n\
+  %l   hour ( 1..12) (a GNU extension)\n\
   %m   month (01..12)\n\
   %M   minute (00..59)\n\
 "), stdout);
       fputs (_("\
   %n   a newline\n\
-  %N   nanoseconds (000000000..999999999)\n\
+  %N   nanoseconds (000000000..999999999) (a GNU extension)\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\
+  %P   like %p, but lower case (a GNU extension)\n\
+  %r   locale's 12-hour time (11:40:27 PM)\n\
+  %R   time, 24-hour; same as %H:%m\n\
   %s   seconds since `00:00:00 1970-01-01 UTC' (a GNU extension)\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\
+  %T   time, 24-hour; same as %H:%M:%S\n\
   %u   day of week (1..7);  1 represents Monday\n\
 "), stdout);
       fputs (_("\
@@ -200,20 +202,31 @@ specifies Coordinated Universal Time.  I
   %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 (01/27/99)\n\
+  %X   locale's 24-hour time representation (14:32:15)\n\
   %y   last two digits of year (00..99)\n\
-  %Y   year (1970...)\n\
+  %Y   year, variable length but at least four characters\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   RFC-2822 style numeric timezone (-0500), blank if not known\n\
+  %Z   time zone name (e.g., EDT), blank if not known\n\
 \n\
 By default, date pads numeric fields with zeroes.  GNU date recognizes\n\
-the following modifiers between `%' and a numeric directive.\n\
+directives that match the BRE `%[-_0^#]?([1-9][0-9]*)?[EO]?[a-zA-Z%]',\n\
+although not all modifiers can be applied to a given directive.  The\n\
+modifiers are:\n\
+\n\
+  `-'    (hyphen) do not pad numeric field (a GNU extension)\n\
+  `_'    (underscore) pad numeric field with spaces (a GNU extension)\n\
+  `0'    (zero) pad numeric field with zeros (a GNU extension)\n\
+"), stdout);
+      fputs (_("\
+  `^'    use upper case in text field (a GNU extension)\n\
+  `#'    change default case in text field (a GNU extension)\n\
+  width  pad the field to the given decimal width (a GNU extension)\n\
+  `E'    use locale's era notations for year field\n\
+  `O'    use locale's alternate digits for numeric field\n\
 \n\
-  `-' (hyphen) do not pad the field\n\
-  `_' (underscore) pad the field with spaces\n\
 "), stdout);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }