Thanks for reporting the problem. It'd be a bit of a pain to implement
your suggestion exactly since the synopsis is generated automatically.
However, I installed the attached to try to attack the problem of
confusion that you reported.
It's been years since I set the date by hand but we might as well be
clear about it, if only for nostalgia's sake.From 45f8f2dd2b54c7f4745c277e3f52f3c99cea5b57 Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@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
