From 45f8f2dd2b54c7f4745c277e3f52f3c99cea5b57 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 4 Feb 2022 18:21:06 -0800
Subject: [PATCH] date: improve doc

Problem reported by Dan Jacobson (Bug#51288).
* doc/coreutils.texi (date invocation, Setting the time)
(Options for date):
* src/date.c (usage): Improve doc.
---
 doc/coreutils.texi | 23 +++++++++++++++--------
 src/date.c         |  3 ++-
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 088d1764c..d3bbf5768 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15976,9 +15976,14 @@ Synopses:
 @example
 date [@var{option}]@dots{} [+@var{format}]
 date [-u|--utc|--universal] @c this avoids a newline in the output
-[ MMDDhhmm[[CC]YY][.ss] ]
+[@var{MMDDhhmm}[[@var{CC}]@var{YY}][.@var{ss}]]
 @end example
 
+The @command{date} command displays the date and time.
+With the @option{--set} (@option{-s}) option, or with
+@samp{[@var{MMDDhhmm}[[@var{CC}]@var{YY}][.@var{ss}]]},
+it sets the date and time.
+
 @vindex LC_TIME
 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.
@@ -16312,17 +16317,18 @@ modifiers are GNU extensions.
 @cindex time setting
 @cindex appropriate privileges
 
-If given an argument that does not start with @samp{+}, @command{date} sets
-the system clock to the date and time specified by that argument (as
-described below).  You must have appropriate privileges to set the
-system clock.  Note for changes to persist across a reboot, the
+You must have appropriate privileges to set the
+system clock.  For changes to persist across a reboot, the
 hardware clock may need to be updated from the system clock, which
 might not happen automatically on your system.
 
-The argument must consist entirely of digits, which have the following
-meaning:
+To set the clock, you can use the @option{--set} (@option{-s}) option
+(@pxref{Options for date}).  To set the clock without using GNU
+extensions, you can give @command{date} an argument of the form
+@samp{@var{MMDDhhmm}[[@var{CC}]@var{YY}][.@var{ss}]} where each two-letter
+component stands for two digits with the following meanings:
 
-@table @samp
+@table @var
 @item MM
 month
 @item DD
@@ -16352,6 +16358,7 @@ relative to Universal Time rather than to the local time zone.
 @cindex options for @command{date}
 
 The program accepts the following options.  Also see @ref{Common options}.
+Except for @option{-u}, these options are all GNU extensions to POSIX.
 
 @table @samp
 
diff --git a/src/date.c b/src/date.c
index 0915d7c64..163141adc 100644
--- a/src/date.c
+++ b/src/date.c
@@ -135,7 +135,8 @@ Usage: %s [OPTION]... [+FORMAT]\n\
 "),
               program_name, program_name);
       fputs (_("\
-Display the current time in the given FORMAT, or set the system date.\n\
+Display date and time in the given FORMAT.\n\
+With -s, or with [MMDDhhmm[[CC]YY][.ss]], set the date and time.\n\
 "), stdout);
 
       emit_mandatory_arg_note ();
-- 
2.34.1