date: new option spelling --rfc-email

* NEWS:
* doc/coreutils.texi (Time conversion specifiers)
(Options for date, Examples of date): Document this.
* src/date.c (rfc_email_format): Rename from rfc_2822_format.
All uses changed.
(usage, long_options): Support --rfc-email.

3 files changed, 22 insertions, 13 deletions

diff --git a/NEWS b/NEWS
index 1832d421a..5036aa69a 100644
--- a/NEWS
+++ b/NEWS
@@ -15,6 +15,11 @@ GNU coreutils NEWS                                    -*- outline -*-
 
 ** Improvements
 
+  The new 'date' option --rfc-email is now the long form for -R.
+  The new option spelling is intended to avoid the need to track the
+  Internet RFC number for email dates (currently RFC 5322).  The old
+  option spellings --rfc-2822 and --rfc-822 still work.
+
   stty now validates arguments before interacting with the device,
   ensuring there are no side effects to specifying an invalid option.
 
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 64243a633..aa8f75481 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15161,7 +15161,7 @@ This may be @samp{60} if leap seconds are supported.
 @item %X
 locale's time representation (e.g., @samp{23:13:48})
 @item %z
-@w{RFC 2822/ISO 8601} style numeric time zone
+@w{RFC 5322/ISO 8601} style numeric time zone
 (e.g., @samp{-0600} or @samp{+0530}), 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
@@ -15503,11 +15503,9 @@ Display the date and time of the last modification of @var{file},
 instead of the current date and time.
 
 @item -R
-@itemx --rfc-822
-@itemx --rfc-2822
+@itemx --rfc-email
 @opindex -R
-@opindex --rfc-822
-@opindex --rfc-2822
+@opindex --rfc-email
 Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
 %z}, evaluated in the C locale so abbreviations are always in English.
 For example:
@@ -15516,11 +15514,16 @@ For example:
 Fri, 09 Sep 2005 13:51:39 -0700
 @end example
 
+@opindex --rfc-822
+@opindex --rfc-2822
 This format conforms to Internet RFCs
 @uref{https://tools.ietf.org/search/rfc5322, 5322},
 @uref{https://tools.ietf.org/search/rfc2822, 822} and
 @uref{https://tools.ietf.org/search/rfc822, 822}, the
 current and previous standards for Internet email.
+For compatibility with older versions of @command{date},
+@option{--rfc-2822} and @option{--rfc-822} are aliases for
+@option{--rfc-email}.
 
 @item --rfc-3339=@var{timespec}
 @opindex --rfc-3339=@var{timespec}
@@ -15650,8 +15653,8 @@ date --set='+2 minutes'
 @end example
 
 @item
-To print the date in RFC 2822 format,
-use @samp{date --rfc-2822}.  Here is some example output:
+To print the date in Internet RFC 5322 format,
+use @samp{date --rfc-email}.  Here is some example output:
 
 @example
 Fri, 09 Sep 2005 13:51:39 -0700
diff --git a/src/date.c b/src/date.c
index ddc702fc7..eed09016d 100644
--- a/src/date.c
+++ b/src/date.c
@@ -72,8 +72,8 @@ static enum Time_spec const time_spec[] =
 };
 ARGMATCH_VERIFY (time_spec_string, time_spec);
 
-/* A format suitable for Internet RFC 2822.  */
-static char const rfc_2822_format[] = "%a, %d %b %Y %H:%M:%S %z";
+/* A format suitable for Internet RFCs 5322, 2822, and 822.  */
+static char const rfc_email_format[] = "%a, %d %b %Y %H:%M:%S %z";
 
 /* For long options that have no equivalent short option, use a
    non-character as a pseudo short option, starting with CHAR_MAX + 1.  */
@@ -92,6 +92,7 @@ static struct option const long_options[] =
   {"file", required_argument, NULL, 'f'},
   {"iso-8601", optional_argument, NULL, 'I'},
   {"reference", required_argument, NULL, 'r'},
+  {"rfc-email", no_argument, NULL, 'R'},
   {"rfc-822", no_argument, NULL, 'R'},
   {"rfc-2822", no_argument, NULL, 'R'},
   {"rfc-3339", required_argument, NULL, RFC_3339_OPTION},
@@ -155,7 +156,7 @@ Display the current time in the given FORMAT, or set the system date.\n\
                                Example: 2006-08-14T02:34:56-06:00\n\
 "), stdout);
       fputs (_("\
-  -R, --rfc-2822             output date and time in RFC 2822 format.\n\
+  -R, --rfc-email            output date and time in RFC 5322 format.\n\
                                Example: Mon, 14 Aug 2006 02:34:56 -0600\n\
 "), stdout);
       fputs (_("\
@@ -414,7 +415,7 @@ main (int argc, char **argv)
           reference = optarg;
           break;
         case 'R':
-          new_format = rfc_2822_format;
+          new_format = rfc_email_format;
           break;
         case 's':
           set_datestr = optarg;
@@ -580,10 +581,10 @@ show_date (const char *format, struct timespec when, timezone_t tz)
 
   if (localtime_rz (tz, &when.tv_sec, &tm))
     {
-      if (format == rfc_2822_format)
+      if (format == rfc_email_format)
         setlocale (LC_TIME, "C");
       fprintftime (stdout, format, &tm, tz, when.tv_nsec);
-      if (format == rfc_2822_format)
+      if (format == rfc_email_format)
         setlocale (LC_TIME, "");
       fputc ('\n', stdout);
       return true;