K.I.S.S.

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/index.html
Description:

for a beginner, your documentation is hard to follow. nowhere does it
discuss how to create a user that have "createdb" and "createrole"
privileges. you should provide a complete chapter for noobs.

also, don't discuss or intermix the discussion of recommended standard way
of doing things. if required, place it in the appendix. your documentation
should just keep discussing working with PostgreSQL, from beginning to
advanced.

you need this kind of explanation

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/index.html
Description:

right off the bat, you should have this kind of explanation up there in
chapter 1:

https://www.liquidweb.com/kb/what-is-the-default-password-for-postgresql/

this will orient any noobs immediately.

also, the word "role" and "user" should not be used interchangebly. they
mean different things.

confusing terms

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/role-membership.html
Description:

https://www.postgresql.org/docs/10/static/role-membership.html

it says

"Once the group role exists, you can add and remove members using the GRANT
and REVOKE commands:

GRANT group_role TO role1, ... ;
REVOKE group_role FROM role1, ... ;"

how can you add members to a newly created group role using the above
command? shouldn't it be GRANT group_role TO user1 ??

Re: AT TIME ZONE correction

[Bruce Momjian]

On Sun, Sep  2, 2018 at 10:11:59PM -0400, Bruce Momjian wrote:
> On Sun, Sep  2, 2018 at 02:21:58PM -0400, Tom Lane wrote:
> > I still find this to be more confusing than helpful.  In particular,
> > I do not think that it's possible to explain this behavior clearly
> > without mentioning that timestamp with time zone values are always
> > stored in UTC and what AT TIME ZONE really does is convert between UTC
> > and the specified zone (in a direction dependent on which type is
> > supplied as argument).
> 
> Agreed.  The more I dig into this the more I learn.  I have developed
> the attached patch which I hope this time is an improvement.

I polished the text some more and changed the three-letter time zone
abbreviation (e.g., MST) to use the more general text, e.g.
"America/Denver".  We should not be encouraging people to specify the
daylight savings time status based on the date in the date/time string.

-- 
  Bruce Momjian  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 +
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bb794e0..2135799 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -8082,10 +8082,11 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');

 

-The AT TIME ZONE construct allows conversions
-of time stamps to different time zones.   shows its
-variants.
+The AT TIME ZONE converts time
+stamp without time zone to/from
+time stamp with time zone, and
+time values to different time zones.  shows its variants.

 
 
@@ -8130,24 +8131,29 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
 

 In these expressions, the desired time zone zone can be
-specified either as a text string (e.g., 'PST')
+specified either as a text string (e.g., 'America/Los_Angeles')
 or as an interval (e.g., INTERVAL '-08:00').
 In the text case, a time zone name can be specified in any of the ways
 described in .

 

-Examples (assuming the local time zone is PST8PDT):
+Examples (assuming the local time zone is America/Los_Angeles):
 
-SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
 Result: 2001-02-16 19:38:40-08
 
-SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
 Result: 2001-02-16 18:38:40
 
-The first example takes a time stamp without time zone and interprets it as MST time
-(UTC-7), which is then converted to PST (UTC-8) for display.  The second example takes
-a time stamp specified in EST (UTC-5) and converts it to local time in MST (UTC-7).
+The first example adds a time zone to a value that lacks it, and
+displays the value using the current TimeZone
+setting.  The second example shifts the time stamp with time zone
+value to the specified time zone, and returns the value without a
+time zone.  This allows storage and display of values different
+from the current TimeZone setting.  Converting
+time values to other time zones uses the currently
+active time zone rules since no date is supplied.

 

Re: you need this kind of explanation

[Michael Paquier]

On Mon, Sep 03, 2018 at 08:05:33AM +, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/10/static/index.html
> Description:
> 
> right off the bat, you should have this kind of explanation up there in
> chapter 1:
> https://www.liquidweb.com/kb/what-is-the-default-password-for-postgresql/
> 
> this will orient any noobs immediately.
> 
> also, the word "role" and "user" should not be used interchangebly. they
> mean different things.

If you have any improvements that you think are adapted about the
documentation of Postgres, please feel free to provide any patch of base
patch that you could use for discussion.  I am not sure if any kind of
information provided in the blog post you are mentioning above makes
much sense though, as the way Postgres is packaged, installed, deployed
and configured depends heavily on the way a given distribution or OS
wants to set it up, which could have many different requirements.
--
Michael


signature.asc
Description: PGP signature