nomination for worst man page - date(1)

[Robert Citek]

X-Received: by 10.49.4.68 with SMTP id i4mr958849qei.15.1363497474784;
Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.49.35.73 with SMTP id f9ls923335qej.27.gmail; Sat, 16 Mar 2013
22:17:54 -0700 (PDT)
X-Received: by 10.224.17.140 with SMTP id s12mr8098136qaa.3.1363497474538;
Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
Received: from mail-qa0-f54.google.com (mail-qa0-f54.google.com [209.85.216.54])
by gmr-mx.google.com with ESMTPS id x1si531502qci.2.2013.03.16.22.17.54
(version=TLSv1 cipherìDHE-RSA-RC4-SHA bits8/128);
Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
Received-SPF: pass (google.com: domain of ***@gmail.com designates 209.85.216.54 as permitted sender) client-ip 9.85.216.54;
Received: by mail-qa0-f54.google.com with SMTP id hg5so1066358qab.13
for <***@googlegroups.com>; Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
X-Received: by 10.49.17.198 with SMTP id q6mr15573615qed.40.1363497474452;
Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
Received: by 10.49.71.105 with HTTP; Sat, 16 Mar 2013 22:17:54 -0700 (PDT)
X-Original-Sender: ***@gmail.com
X-Original-Authentication-Results: gmr-mx.google.com; spf=pass
(google.com: domain of ***@gmail.com designates 209.85.216.54 as
permitted sender) smtp.mail=***@gmail.com; dkim=pass header.i=@gmail.com
Precedence: list
Mailing-list: list ***@googlegroups.com; contact cwelug+***@googlegroups.com
List-ID: <cwelug.googlegroups.com>
X-Google-Group-Id: 960259670415
List-Post: <http://groups.google.com/group/cwelug/post?hl=en>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en>, <mailto:cwelug+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/cwelug?hl=en>
Sender: ***@googlegroups.com
List-Unsubscribe: <http://groups.google.com/group/cwelug/subscribe?hl=en>, <mailto:googlegroups-manage+960259670415+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.org.user-groups.linux.cwelug/8633>

I am curious to know what people think is the most poorly written man page?

My nomination is for 'date(1)'.

I spent quite some time Googling how to convert Unix epoch time
(seconds) to "readable" format. The solution was this:

$ date --date=@1363483846
Sat Mar 16 21:30:46 EDT 2013

Give the very sparse, cryptic description for the -d option, how does
one make the leap to use @seconds for STRING?

-d, --date=STRING
display time described by STRING, not ‘now’

Not only is this this description cryptic, but it obscures one of the
most useful features for using the date command: date calculations.
For example, the warranty on one of our systems expires in 378 days.
What date is that?

today=$(date +%s)
days=$(( 378*24*60*60 ))
future=$(( $today + $days ))
date --date=@${future}
--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
To post: ***@googlegroups.com
To subscribe: cwelug-***@googlegroups.com
To unsubscribe: cwelug-***@googlegroups.com
More options: http://groups.google.com/group/cwelug
---
You received this message because you are subscribed to the Google Groups "Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cwelug+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Robert Citek]

X-Received: by 10.49.5.129 with SMTP id s1mr1015678qes.39.1363550239008;
Sun, 17 Mar 2013 12:57:19 -0700 (PDT)
X-BeenThere: ***@googlegroups.com
Received: by 10.49.94.139 with SMTP id dc11ls1120815qeb.1.gmail; Sun, 17 Mar
2013 12:57:18 -0700 (PDT)
X-Received: by 10.224.17.140 with SMTP id s12mr9813305qaa.3.1363550238337;
Sun, 17 Mar 2013 12:57:18 -0700 (PDT)
Received: from mail-qa0-f53.google.com (mail-qa0-f53.google.com [209.85.216.53])
by gmr-mx.google.com with ESMTPS id x1si654276qci.2.2013.03.17.12.57.18
(version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128);
Sun, 17 Mar 2013 12:57:18 -0700 (PDT)
Received-SPF: pass (google.com: domain of ***@gmail.com designates 209.85.216.53 as permitted sender) client-ip=209.85.216.53;
Received: by mail-qa0-f53.google.com with SMTP id z4so1270259qan.12
for <***@googlegroups.com>; Sun, 17 Mar 2013 12:57:18 -0700 (PDT)
X-Received: by 10.224.220.211 with SMTP id hz19mr14943631qab.49.1363550238268;
Sun, 17 Mar 2013 12:57:18 -0700 (PDT)
Received: by 10.49.71.105 with HTTP; Sun, 17 Mar 2013 12:57:18 -0700 (PDT)
In-Reply-To: <127C711A-7819-4EDA-A413-***@sluug.org>
X-Original-Sender: ***@gmail.com
X-Original-Authentication-Results: gmr-mx.google.com; spf=pass
(google.com: domain of ***@gmail.com designates 209.85.216.53 as
permitted sender) smtp.mail=***@gmail.com; dkim=pass header.i=@gmail.com
Precedence: list
Mailing-list: list ***@googlegroups.com; contact cwelug+***@googlegroups.com
List-ID: <cwelug.googlegroups.com>
X-Google-Group-Id: 960259670415
List-Post: <http://groups.google.com/group/cwelug/post?hl=en>, <mailto:***@googlegroups.com>
List-Help: <http://groups.google.com/support/?hl=en>, <mailto:cwelug+***@googlegroups.com>
List-Archive: <http://groups.google.com/group/cwelug?hl=en>
Sender: ***@googlegroups.com
List-Unsubscribe: <http://groups.google.com/group/cwelug/subscribe?hl=en>, <mailto:googlegroups-manage+960259670415+***@googlegroups.com>
Archived-At: <http://permalink.gmane.org/gmane.org.user-groups.linux.cwelug/8634>

-d dst Set the kernel's value for daylight saving time. If dst is non-zero, future calls to gettimeofday(2)
will return a non-zero for tz_dsttime.
date +%F --date=05/12/1953
1953-05-12

Exactly. One use of the date command is to display various date/time
formats. By default, date uses the current system time and timezone.
But the --date= option enables date to use an alternate date/time
specified by STRING. What range of possible strings are valid is not
immediately obvious. It's as though the STRING section of the manual
was omitted.

Some examples:

# default, today, now -- all equivalent
date
date --date=now
date --date=today

# unix epoch
date --date=@0
date --date=@0 -u

# past, future
date --date=yesterday
date --date=tomorrow
date --date="next week"
date --date="last week"

# future day of week, Sunday-Saturday, abbreviations work. Midnight
local timezone.
date --date=sat
date --date=sat -u

# 1-2 digit number == today's hour (0-23), local timezone, unless specified
date --date=10
date --date=10 -R
date --date=10 -R -u

# 3-4 digit numbers == today's time
date --date=010
date --date=1010

# 5-?? digit numbers == a date; 6-digit dates are assumed to be 1900
or 2000 years
date --date=71010 -u
date --date=871010 -u
date --date=0871010 -u
date --date=9871010 -u
date --date=19871010 -u

What surprises me is that I have not found any of this information
described in the man pages. Instead, it is documented in the info
pages, but again somewhat cryptically and with few examples.

Regards,
- Robert
--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
To post: ***@googlegroups.com
To subscribe: cwelug-***@googlegroups.com
To unsubscribe: cwelug-***@googlegroups.com
More options: http://groups.google.com/group/cwelug
---
You received this message because you are subscribed to the Google Groups "Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cwelug+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[David Dooling]

My date(1) man page has the text below near the end (from date (GNU
coreutils) 8.13), which seems to provide the information you want.

The info/man dichotomy in GNU is unfortunate, especially since lots of
distributions don't have info pages available unless you install the -doc
package for the utility. info was a good idea when there was no internet or
Google, it's less useful now. Searching for "date coreutils" quickly gets
you to this:


http://www.gnu.org/software/coreutils/manual/html_node/date-invocation.html#date-invocation
EXAMPLES
Convert seconds since the epoch (1970-01-01 UTC) to a date

$ date --date='@2147483647'

Show the time on the west coast of the US (use tzselect(1) to find
TZ)

$ TZ='America/Los_Angeles' date

Show the local time for 9AM next Friday on the west coast of the US

$ date --date='TZ="America/Los_Angeles" 09:00 next Fri'

DATE STRING
The --date=STRING is a mostly free format human readable date
string such as "Sun, 29 Feb 2004
16:21:42 -0800" or "2004-02-29 16:21:42" or even "next Thursday".
A date string may contain
items indicating calendar date, time of day, time zone, day of
week, relative time, relative
date, and numbers. An empty string indicates the beginning of the
day. The date string format
is more complex than is easily documented here but is fully
described in the info documentation.

Very interesting! On my MAcBook there is not a --date parameter and -d

-d dst Set the kernel's value for daylight saving time. If dst

is non-zero, future calls to gettimeofday(2)

will return a non-zero for tz_dsttime.

My experience with --date was as a way to convert formats in bash

date +%F --date=05/12/1953
1953-05-12

Exactly. One use of the date command is to display various date/time
formats. By default, date uses the current system time and timezone.
But the --date= option enables date to use an alternate date/time
specified by STRING. What range of possible strings are valid is not
immediately obvious. It's as though the STRING section of the manual
was omitted.
# default, today, now -- all equivalent
date
date --date=now
date --date=today
# unix epoch
# past, future
date --date=yesterday
date --date=tomorrow
date --date="next week"
date --date="last week"
# future day of week, Sunday-Saturday, abbreviations work. Midnight
local timezone.
date --date=sat
date --date=sat -u
# 1-2 digit number == today's hour (0-23), local timezone, unless specified
date --date=10
date --date=10 -R
date --date=10 -R -u
# 3-4 digit numbers == today's time
date --date=010
date --date=1010
# 5-?? digit numbers == a date; 6-digit dates are assumed to be 1900
or 2000 years
date --date=71010 -u
date --date=871010 -u
date --date=0871010 -u
date --date=9871010 -u
date --date=19871010 -u
What surprises me is that I have not found any of this information
described in the man pages. Instead, it is documented in the info
pages, but again somewhat cryptically and with few examples.
Regards,
- Robert
--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
More options: http://groups.google.com/group/cwelug
---
You received this message because you are subscribed to the Google Groups
"Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/groups/opt_out.
--
David Dooling

--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
To post: ***@googlegroups.com
To subscribe: cwelug-***@googlegroups.com
To unsubscribe: cwelug-***@googlegroups.com
More options: http://groups.google.com/group/cwelug
---
You received this message because you are subscribed to the Google Groups "Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cwelug+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Robert Citek]

You're welcome. Hope someone somewhere finds it useful.

A bit of back story ...

The reason I wanted to know how to work with date was because we have
a number of systems with RAID controllers that automatically discharge
and recharge their batteries. This is called the battery relearn
cycle and, apparently, is a good thing for the battery. That relearn
cycle is not such a good thing for disk I/O performance. And it is
really bad when it happens during peak hours on high volume production
servers.

Unfortunately, you can't turn the relearn cycle off. Nor can you
reschedule it on the controller.

However, the controller does show the number of days before the next
relearn cycle. And you can manually force a relearn. If we could
calculate the date of the next automatic relearn cycle, then we could
schedule a manual relearn cycle for an earlier date/time that would be
more convenient for us.

So, the challenge was to calculate the date of the Saturday before the
next automatic relearn cycle.

Here's one solution:

dbnr=72 # days before next relearn
delta=$(( ${dbnr}*24*60*60 )) # dbnr days in seconds
today=$(date +%s -d 0) # today at midnight in seconds
future=$(( ${today} + ${delta} )) # future in seconds
dow=$(date +%w -d @${future}) # numeric day of week of future
dts=$(( 6 - 7 - ${dow} )) # number of days to previous
Saturday(6) in future
rdt=$(( ${future} + (${dts}*24*60*60) )) # relearn date in seconds

Display the future date:

date -d @${rdt}

To schedule something in the future using the 'at' command:

atdt=$(date +%Y%m%d%H%M.%S -d @${rdt}) # date format suitable for at -t
at -f ~/bin/relearn.sh -t ${atdt} # scheduling the relearn for
a Saturday morning

This isn't perfect as it doesn't handle a few edge cases. But works
good enough for our use cases.

Regards,
- Robert

Thank you very much for this! It is now going into Linux Phrasebook, volume
2.
Scott
--
R. Scott Granneman
“One of the differences between people who do science and people who don’t
is the people who do science realize that what you’re trying to do in
science is falsify a hypothesis. And only after you examine all sorts of
evidence and you can’t falsify a hypothesis do you establish that the
hypothesis is true. The people trying to prove a hypothesis look at any
piece of positive evidence and then stop.”
---Peter Rosen, emergency room doctor

Post by Robert Citek

-d dst Set the kernel's value for daylight saving time. If dst
is non-zero, future calls to gettimeofday(2)
will return a non-zero for tz_dsttime.
date +%F --date=05/12/1953
1953-05-12

Exactly. One use of the date command is to display various date/time
formats. By default, date uses the current system time and timezone.
But the --date= option enables date to use an alternate date/time
specified by STRING. What range of possible strings are valid is not
immediately obvious. It's as though the STRING section of the manual
was omitted.
# default, today, now -- all equivalent
date
date --date=now
date --date=today
# unix epoch
# past, future
date --date=yesterday
date --date=tomorrow
date --date="next week"
date --date="last week"
# future day of week, Sunday-Saturday, abbreviations work. Midnight
local timezone.
date --date=sat
date --date=sat -u
# 1-2 digit number == today's hour (0-23), local timezone, unless specified
date --date=10
date --date=10 -R
date --date=10 -R -u
# 3-4 digit numbers == today's time
date --date=010
date --date=1010
# 5-?? digit numbers == a date; 6-digit dates are assumed to be 1900
or 2000 years
date --date=71010 -u
date --date=871010 -u
date --date=0871010 -u
date --date=9871010 -u
date --date=19871010 -u
What surprises me is that I have not found any of this information
described in the man pages. Instead, it is documented in the info
pages, but again somewhat cryptically and with few examples.
Regards,
- Robert

--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
More options: http://groups.google.com/group/cwelug
--- You received this message because you are subscribed to the Google
Groups "Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/groups/opt_out.

--
--
Central West End Linux Users Group (via Google Groups)
Main page: http://www.cwelug.org
To post: ***@googlegroups.com
To subscribe: cwelug-***@googlegroups.com
To unsubscribe: cwelug-***@googlegroups.com
More options: http://groups.google.com/group/cwelug
---
You received this message because you are subscribed to the Google Groups "Central West End Linux Users Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cwelug+***@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.