pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAmbiguous language in Table 8.13. Special Date/Time Inputs
12+ messages / 5 participants
[nested] [flat]
Commits from this thread:
2019-10-07 cae078f3f9 e61cc3576d f68d5bff5e 1b1339838d 315c7a8153 630a8f5e2d ccdfac8286 docs: clarify that today/tomorrow/yesterday is at 00:00
* Ambiguous language in Table 8.13. Special Date/Time Inputs
@ 2019-07-08 10:07 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 12+ messages in thread
From: PG Doc comments form @ 2019-07-08 10:07 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: adh@sanger.ac.uk
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/11/datatype-datetime.html
Description:
In Table 8.13. Special Date/Time Inputs, the description for the special
values 'today', 'tomorrow' and 'yesterday' uses the word 'midnight' e.g. the
special value 'today' is defined as 'midnight today'. I propose that the
word 'midnight' is ambiguous, because it can be interpreted either as
midnight at the start of the day in question, or midnight at the end of the
day. This ambiguity can be avoided if 'midnight' is replaced by '00:00:00',
or better, '00:00:00 local time'. Astronomers have deprecated the word
'midnight' for many years precisely to avoid this ambiguity.
David Harper
Senior DBA (and former astronomer)
Wellcome Sanger Institute
Cambridge, England
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs
@ 2019-07-09 03:32 Bruce Momjian <bruce@momjian.us>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 12+ messages in thread
From: Bruce Momjian @ 2019-07-09 03:32 UTC (permalink / raw)
To: adh@sanger.ac.uk; pgsql-docs@lists.postgresql.org
On Mon, Jul 8, 2019 at 10:07:59AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/11/datatype-datetime.html
> Description:
>
> In Table 8.13. Special Date/Time Inputs, the description for the special
> values 'today', 'tomorrow' and 'yesterday' uses the word 'midnight' e.g. the
> special value 'today' is defined as 'midnight today'. I propose that the
> word 'midnight' is ambiguous, because it can be interpreted either as
> midnight at the start of the day in question, or midnight at the end of the
> day. This ambiguity can be avoided if 'midnight' is replaced by '00:00:00',
> or better, '00:00:00 local time'. Astronomers have deprecated the word
> 'midnight' for many years precisely to avoid this ambiguity.
Uh, I believe midnight is always the start of the day. I think
00:00:00 looks awkward.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-09 08:14 David Harper <adh@sanger.ac.uk>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 12+ messages in thread
From: David Harper @ 2019-07-09 08:14 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
> Uh, I believe midnight is always the start of the day.
The U.S. National Institute of Standards and Technology (NIST) deprecates the term “midnight” as ambiguous and recommmends the use of 24-hour clock notation:
===== BEGIN QUOTE =====
When someone refers to "midnight tonight" or "midnight last night" the reference of time is obvious. However, if a date/time is referred to as "at midnight on Friday, October 20th" the intention could be either midnight the beginning of the day or midnight at the end of the day.
To avoid ambiguity, specification of an event as occurring on a particular day at 11:59 p.m. or 12:01 a.m. is a good idea, especially legal documents such as contracts and insurance policies. Another option would be to use 24-hour clock, using the designation of 0000 to refer to midnight at the beginning of a given day (or date) and 2400 to designate the end of a given day (or date).
===== END QUOTE =====
Source:
https://www.nist.gov/pml/time-and-frequency-division/times-day-faqs
> I think 00:00:00 looks awkward.
Perhaps, but in technical documentation, accuracy should have priority over aesthetics, surely?
David Harper
Wellcome Sanger Institute, Cambridge, England
--
The Wellcome Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-09 15:48 Bruce Momjian <bruce@momjian.us>
parent: David Harper <adh@sanger.ac.uk>
0 siblings, 1 reply; 12+ messages in thread
From: Bruce Momjian @ 2019-07-09 15:48 UTC (permalink / raw)
To: David Harper <adh@sanger.ac.uk>; +Cc: pgsql-docs@lists.postgresql.org
On Tue, Jul 9, 2019 at 09:14:27AM +0100, David Harper wrote:
> > Uh, I believe midnight is always the start of the day.
>
> The U.S. National Institute of Standards and Technology (NIST) deprecates the term “midnight” as ambiguous and recommmends the use of 24-hour clock notation:
>
> ===== BEGIN QUOTE =====
> When someone refers to "midnight tonight" or "midnight last night" the reference of time is obvious. However, if a date/time is referred to as "at midnight on Friday, October 20th" the intention could be either midnight the beginning of the day or midnight at the end of the day.
>
> To avoid ambiguity, specification of an event as occurring on a particular day at 11:59 p.m. or 12:01 a.m. is a good idea, especially legal documents such as contracts and insurance policies. Another option would be to use 24-hour clock, using the designation of 0000 to refer to midnight at the beginning of a given day (or date) and 2400 to designate the end of a given day (or date).
> ===== END QUOTE =====
>
> Source:
>
> https://www.nist.gov/pml/time-and-frequency-division/times-day-faqs
>
> > I think 00:00:00 looks awkward.
>
> Perhaps, but in technical documentation, accuracy should have priority over aesthetics, surely?
>
Yes, I see what you mean now. How is this patch, which uses "zero
hour"?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
Attachments:
zero.diff (text/x-diff, 1.0K) download
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 35ecd48ed5..3b5b8a65d0 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2174,17 +2174,17 @@ January 8 04:05:06 1999 PST
<row>
<entry><literal>today</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight today</entry>
+ <entry>midnight (zero hour) today</entry>
</row>
<row>
<entry><literal>tomorrow</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight tomorrow</entry>
+ <entry>midnight (zero hour) tomorrow</entry>
</row>
<row>
<entry><literal>yesterday</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight yesterday</entry>
+ <entry>midnight (zero hour) yesterday</entry>
</row>
<row>
<entry><literal>allballs</literal></entry>
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-09 15:58 Tom Lane <tgl@sss.pgh.pa.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 12+ messages in thread
From: Tom Lane @ 2019-07-09 15:58 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: David Harper <adh@sanger.ac.uk>; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> Yes, I see what you mean now. How is this patch, which uses "zero
> hour"?
Ugh. Are we writing spy novels now?
I actually agree with your opinion that "midnight" is fine.
That text has been that way for over fifteen years[1], and
nobody's complained before that it was ambiguous.
But, if we're going to change it, let's just s/midnight/00:00:00/
and be done. Making up fancy terminology doesn't improve matters.
regards, tom lane
[1] git blame dates the text to commit 1b342df00 of 2002-11-11, and
apparently it was not new then, but I'm too lazy to dig further.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-10 10:13 David Harper <adh@sanger.ac.uk>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 12+ messages in thread
From: David Harper @ 2019-07-10 10:13 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
> I actually agree with your opinion that "midnight" is fine.
> That text has been that way for over fifteen years[1], and
> nobody's complained before that it was ambiguous.
Conversely, how many users over the past fifteen years have read that table, and then felt compelled (as I did) to run a query such as
select 'today'::timestamp,'yesterday'::timestamp,'tomorrow'::timestamp;
on their PostgreSQL cluster to clear the ambiguity for themselves?
Best regards
David Harper
Wellcome Sanger Institute, Cambridge, England
--
The Wellcome Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-10 17:32 Jonathan S. Katz <jkatz@postgresql.org>
parent: David Harper <adh@sanger.ac.uk>
0 siblings, 1 reply; 12+ messages in thread
From: Jonathan S. Katz @ 2019-07-10 17:32 UTC (permalink / raw)
To: David Harper <adh@sanger.ac.uk>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
On 7/10/19 6:13 AM, David Harper wrote:
>> I actually agree with your opinion that "midnight" is fine.
>> That text has been that way for over fifteen years[1], and
>> nobody's complained before that it was ambiguous.
>
> Conversely, how many users over the past fifteen years have read that table, and then felt compelled (as I did) to run a query such as
>
> select 'today'::timestamp,'yesterday'::timestamp,'tomorrow'::timestamp;
>
> on their PostgreSQL cluster to clear the ambiguity for themselves?
I've heard of one, but only just recently :)
If we were to s/midnight/00:00:00/ we'd probably want to do it
everywhere midnight appears. This occurs in a few places in the docs:
https://www.postgresql.org/docs/current/functions-formatting.html (SSSS)
https://www.postgresql.org/docs/current/protocol-replication.html
(XlogData section)
and there are some various code comments as well.
Count me as a +0 vote, as I've always interpreted it the way Bruce & Tom
said upthread, but if we want to change it I can write a patch.
Jonathan
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-10 18:26 Bruce Momjian <bruce@momjian.us>
parent: Jonathan S. Katz <jkatz@postgresql.org>
0 siblings, 1 reply; 12+ messages in thread
From: Bruce Momjian @ 2019-07-10 18:26 UTC (permalink / raw)
To: Jonathan S. Katz <jkatz@postgresql.org>; +Cc: David Harper <adh@sanger.ac.uk>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs@lists.postgresql.org
On Wed, Jul 10, 2019 at 01:32:31PM -0400, Jonathan Katz wrote:
> On 7/10/19 6:13 AM, David Harper wrote:
> >> I actually agree with your opinion that "midnight" is fine.
> >> That text has been that way for over fifteen years[1], and
> >> nobody's complained before that it was ambiguous.
> >
> > Conversely, how many users over the past fifteen years have read that table, and then felt compelled (as I did) to run a query such as
> >
> > select 'today'::timestamp,'yesterday'::timestamp,'tomorrow'::timestamp;
> >
> > on their PostgreSQL cluster to clear the ambiguity for themselves?
>
> I've heard of one, but only just recently :)
>
> If we were to s/midnight/00:00:00/ we'd probably want to do it
> everywhere midnight appears. This occurs in a few places in the docs:
>
> https://www.postgresql.org/docs/current/functions-formatting.html (SSSS)
> https://www.postgresql.org/docs/current/protocol-replication.html
> (XlogData section)
>
> and there are some various code comments as well.
>
> Count me as a +0 vote, as I've always interpreted it the way Bruce & Tom
> said upthread, but if we want to change it I can write a patch.
The thing I don't like about 00:00:00 is that it is a lot of information
to say "the start of the day", while I assumed midnight was clear on
that. If we can find a way to say "start of the day (midnight)", that
would work.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-10 18:50 Tom Lane <tgl@sss.pgh.pa.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 12+ messages in thread
From: Tom Lane @ 2019-07-10 18:50 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Jonathan S. Katz <jkatz@postgresql.org>; David Harper <adh@sanger.ac.uk>; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> The thing I don't like about 00:00:00 is that it is a lot of information
> to say "the start of the day", while I assumed midnight was clear on
> that. If we can find a way to say "start of the day (midnight)", that
> would work.
One really simple way to make it shorter is to say "00:00", leaving
out the seconds.
regards, tom lane
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-11 08:34 David Harper <adh@sanger.ac.uk>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 12+ messages in thread
From: David Harper @ 2019-07-11 08:34 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Bruce Momjian <bruce@momjian.us>; Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
> One really simple way to make it shorter is to say "00:00", leaving
> out the seconds.
That’s a good solution. It removes the long-standing ambiguity without looking too ugly.
Best regards
David Harper
Wellcome Sanger Institute, Cambridge, England
--
The Wellcome Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-07-11 14:42 Bruce Momjian <bruce@momjian.us>
parent: David Harper <adh@sanger.ac.uk>
0 siblings, 1 reply; 12+ messages in thread
From: Bruce Momjian @ 2019-07-11 14:42 UTC (permalink / raw)
To: David Harper <adh@sanger.ac.uk>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
On Thu, Jul 11, 2019 at 09:34:58AM +0100, David Harper wrote:
> > One really simple way to make it shorter is to say "00:00", leaving
> > out the seconds.
>
> That’s a good solution. It removes the long-standing ambiguity without looking too ugly.
OK, how is this patch?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
Attachments:
midnight.diff (text/x-diff, 1.1K) download
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 35ecd48ed5..ce9d2dddf1 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2174,17 +2174,17 @@ January 8 04:05:06 1999 PST
<row>
<entry><literal>today</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight today</entry>
+ <entry>midnight (<literal>00:00</literal>) today</entry>
</row>
<row>
<entry><literal>tomorrow</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight tomorrow</entry>
+ <entry>midnight (<literal>00:00</literal>) tomorrow</entry>
</row>
<row>
<entry><literal>yesterday</literal></entry>
<entry><type>date</type>, <type>timestamp</type></entry>
- <entry>midnight yesterday</entry>
+ <entry>midnight (<literal>00:00</literal>) yesterday</entry>
</row>
<row>
<entry><literal>allballs</literal></entry>
* Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT]
@ 2019-10-07 21:27 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 12+ messages in thread
From: Bruce Momjian @ 2019-10-07 21:27 UTC (permalink / raw)
To: David Harper <adh@sanger.ac.uk>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
On Thu, Jul 11, 2019 at 10:42:35AM -0400, Bruce Momjian wrote:
> On Thu, Jul 11, 2019 at 09:34:58AM +0100, David Harper wrote:
> > > One really simple way to make it shorter is to say "00:00", leaving
> > > out the seconds.
> >
> > That’s a good solution. It removes the long-standing ambiguity without looking too ugly.
>
> OK, how is this patch?
Doc patch applied to all current branches. Thanks for the report.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2019-10-07 21:27 UTC | newest]
Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-07-08 10:07 Ambiguous language in Table 8.13. Special Date/Time Inputs PG Doc comments form <noreply@postgresql.org>
2019-07-09 03:32 ` Bruce Momjian <bruce@momjian.us>
2019-07-09 08:14 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] David Harper <adh@sanger.ac.uk>
2019-07-09 15:48 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Bruce Momjian <bruce@momjian.us>
2019-07-09 15:58 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Tom Lane <tgl@sss.pgh.pa.us>
2019-07-10 10:13 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] David Harper <adh@sanger.ac.uk>
2019-07-10 17:32 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Jonathan S. Katz <jkatz@postgresql.org>
2019-07-10 18:26 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Bruce Momjian <bruce@momjian.us>
2019-07-10 18:50 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Tom Lane <tgl@sss.pgh.pa.us>
2019-07-11 08:34 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] David Harper <adh@sanger.ac.uk>
2019-07-11 14:42 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Bruce Momjian <bruce@momjian.us>
2019-10-07 21:27 ` Re: Ambiguous language in Table 8.13. Special Date/Time Inputs [EXT] Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox