pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feeddocumentation suggestion
23+ messages / 8 participants
[nested] [flat]
* documentation suggestion
@ 2011-08-23 22:57 Rob Sargent <robjsargent@gmail.com>
0 siblings, 1 reply; 23+ messages in thread
From: Rob Sargent @ 2011-08-23 22:57 UTC (permalink / raw)
To: pgsql-general@postgresql.org
Apologies if this is the wrong forum.
If there has been a suggestion to get the "Up" hyperlink placed also
at/near the top of the page, please add my vote. Else could this be
considered as a feature request?
rjs
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: documentation suggestion
@ 2011-08-24 03:45 Bruce Momjian <bruce@momjian.us>
parent: Rob Sargent <robjsargent@gmail.com>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2011-08-24 03:45 UTC (permalink / raw)
To: Rob Sargent <robjsargent@gmail.com>; +Cc: pgsql-general@postgresql.org, Peter Eisentraut <peter_e@gmx.net>
Rob Sargent wrote:
> Apologies if this is the wrong forum.
>
> If there has been a suggestion to get the "Up" hyperlink placed also
> at/near the top of the page, please add my vote. Else could this be
> considered as a feature request?
I have talked to Peter Eisentraut on several occasions during the past
nine months requesting these changes. Peter, can you make this change
or give me a hint on how I can do it?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: documentation suggestion
@ 2011-08-24 04:55 Rob Sargent <robjsargent@gmail.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Rob Sargent @ 2011-08-24 04:55 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-general@postgresql.org, Peter Eisentraut <peter_e@gmx.net>
Bruce Momjian wrote:
> Rob Sargent wrote:
>
>> Apologies if this is the wrong forum.
>>
>> If there has been a suggestion to get the "Up" hyperlink placed also
>> at/near the top of the page, please add my vote. Else could this be
>> considered as a feature request?
>>
>
> I have talked to Peter Eisentraut on several occasions during the past
> nine months requesting these changes. Peter, can you make this change
> or give me a hint on how I can do it?
>
>
Is the build system of the web-site also downloadable? I could possibly
take a peek. (In a couple of weeks, that is. Vaction.)
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [GENERAL] documentation suggestion
@ 2011-08-24 12:33 Bruce Momjian <bruce@momjian.us>
parent: Rob Sargent <robjsargent@gmail.com>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2011-08-24 12:33 UTC (permalink / raw)
To: Rob Sargent <robjsargent@gmail.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; pgsql-docs
Rob Sargent wrote:
>
>
> Bruce Momjian wrote:
> > Rob Sargent wrote:
> >
> >> Apologies if this is the wrong forum.
> >>
> >> If there has been a suggestion to get the "Up" hyperlink placed also
> >> at/near the top of the page, please add my vote. Else could this be
> >> considered as a feature request?
> >>
> >
> > I have talked to Peter Eisentraut on several occasions during the past
> > nine months requesting these changes. Peter, can you make this change
> > or give me a hint on how I can do it?
> >
> >
> Is the build system of the web-site also downloadable? I could possibly
> take a peek. (In a couple of weeks, that is. Vaction.)
[ Discussion moved to docs ]
Yes, it is all online in doc/src/sgml. I think the file that needs to
be modified is stylesheet.dsl.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [GENERAL] documentation suggestion
@ 2011-08-24 18:59 Peter Eisentraut <peter_e@gmx.net>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Peter Eisentraut @ 2011-08-24 18:59 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Rob Sargent <robjsargent@gmail.com>; pgsql-docs
On ons, 2011-08-24 at 08:33 -0400, Bruce Momjian wrote:
> Rob Sargent wrote:
> >
> >
> > Bruce Momjian wrote:
> > > Rob Sargent wrote:
> > >
> > >> Apologies if this is the wrong forum.
> > >>
> > >> If there has been a suggestion to get the "Up" hyperlink placed also
> > >> at/near the top of the page, please add my vote. Else could this be
> > >> considered as a feature request?
> > >>
> > >
> > > I have talked to Peter Eisentraut on several occasions during the past
> > > nine months requesting these changes. Peter, can you make this change
> > > or give me a hint on how I can do it?
> > >
> > >
> > Is the build system of the web-site also downloadable? I could possibly
> > take a peek. (In a couple of weeks, that is. Vaction.)
>
> [ Discussion moved to docs ]
>
> Yes, it is all online in doc/src/sgml. I think the file that needs to
> be modified is stylesheet.dsl.
We did play around with it, but none of the solutions looked satisfying.
Where exactly would you want the "Up" to be placed?
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [GENERAL] documentation suggestion
@ 2011-08-25 03:40 Bruce Momjian <bruce@momjian.us>
parent: Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2011-08-25 03:40 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: Rob Sargent <robjsargent@gmail.com>; pgsql-docs
Peter Eisentraut wrote:
> On ons, 2011-08-24 at 08:33 -0400, Bruce Momjian wrote:
> > Rob Sargent wrote:
> > >
> > >
> > > Bruce Momjian wrote:
> > > > Rob Sargent wrote:
> > > >
> > > >> Apologies if this is the wrong forum.
> > > >>
> > > >> If there has been a suggestion to get the "Up" hyperlink placed also
> > > >> at/near the top of the page, please add my vote. Else could this be
> > > >> considered as a feature request?
> > > >>
> > > >
> > > > I have talked to Peter Eisentraut on several occasions during the past
> > > > nine months requesting these changes. Peter, can you make this change
> > > > or give me a hint on how I can do it?
> > > >
> > > >
> > > Is the build system of the web-site also downloadable? I could possibly
> > > take a peek. (In a couple of weeks, that is. Vaction.)
> >
> > [ Discussion moved to docs ]
> >
> > Yes, it is all online in doc/src/sgml. I think the file that needs to
> > be modified is stylesheet.dsl.
>
> We did play around with it, but none of the solutions looked satisfying.
>
> Where exactly would you want the "Up" to be placed?
Here is my request from Feb 2, 2011:
Peter, based on feedback we have received, I think our users want our
docs header to look the same as our docs footer, i.e. few people see
the value of Fast Forward and Fast Backward, and they want "Up" to be in
the header. You seem to have done all the substantive changes to
stylesheet.dsl --- would you make these changes? Thanks.
and from March 11:
OK, so here is a summary:
o remove fast forward/backward links
o add book title where there is no heading
o make book and chapter titles as links
o make the bottom footer match the top header
Not sure which suggestion you want but anything that adds "Up"
functionality, either with the "Up" literal or the chapter title that is
"up" would be an improvement.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [GENERAL] documentation suggestion
@ 2011-08-27 20:34 Peter Eisentraut <peter_e@gmx.net>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Peter Eisentraut @ 2011-08-27 20:34 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Rob Sargent <robjsargent@gmail.com>; pgsql-docs
On ons, 2011-08-24 at 23:40 -0400, Bruce Momjian wrote:
> Peter Eisentraut wrote:
> > On ons, 2011-08-24 at 08:33 -0400, Bruce Momjian wrote:
> > > Rob Sargent wrote:
> > > >
> > > >
> > > > Bruce Momjian wrote:
> > > > > Rob Sargent wrote:
> > > > >
> > > > >> Apologies if this is the wrong forum.
> > > > >>
> > > > >> If there has been a suggestion to get the "Up" hyperlink placed also
> > > > >> at/near the top of the page, please add my vote. Else could this be
> > > > >> considered as a feature request?
> > > > >>
> > > > >
> > > > > I have talked to Peter Eisentraut on several occasions during the past
> > > > > nine months requesting these changes. Peter, can you make this change
> > > > > or give me a hint on how I can do it?
> > > > >
> > > > >
> > > > Is the build system of the web-site also downloadable? I could possibly
> > > > take a peek. (In a couple of weeks, that is. Vaction.)
> > >
> > > [ Discussion moved to docs ]
> > >
> > > Yes, it is all online in doc/src/sgml. I think the file that needs to
> > > be modified is stylesheet.dsl.
> >
> > We did play around with it, but none of the solutions looked satisfying.
> >
> > Where exactly would you want the "Up" to be placed?
>
> Here is my request from Feb 2, 2011:
>
> Peter, based on feedback we have received, I think our users want our
> docs header to look the same as our docs footer, i.e. few people see
> the value of Fast Forward and Fast Backward, and they want "Up" to be in
> the header. You seem to have done all the substantive changes to
> stylesheet.dsl --- would you make these changes? Thanks.
>
> and from March 11:
>
> OK, so here is a summary:
>
> o remove fast forward/backward links
> o add book title where there is no heading
> o make book and chapter titles as links
> o make the bottom footer match the top header
>
> Not sure which suggestion you want but anything that adds "Up"
> functionality, either with the "Up" literal or the chapter title that is
> "up" would be an improvement.
Yes, but where do you want the "Up" placed?
Take a random page, such as this one:
http://developer.postgresql.org/pgdocs/postgres/queries-table-expressions.html
Where should the "Up" at the top go?
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [GENERAL] documentation suggestion
@ 2011-09-01 11:53 Bruce Momjian <bruce@momjian.us>
parent: Peter Eisentraut <peter_e@gmx.net>
0 siblings, 0 replies; 23+ messages in thread
From: Bruce Momjian @ 2011-09-01 11:53 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: Rob Sargent <robjsargent@gmail.com>; pgsql-docs
Peter Eisentraut wrote:
> > > > Yes, it is all online in doc/src/sgml. I think the file that needs to
> > > > be modified is stylesheet.dsl.
> > >
> > > We did play around with it, but none of the solutions looked satisfying.
> > >
> > > Where exactly would you want the "Up" to be placed?
> >
> > Here is my request from Feb 2, 2011:
> >
> > Peter, based on feedback we have received, I think our users want our
> > docs header to look the same as our docs footer, i.e. few people see
> > the value of Fast Forward and Fast Backward, and they want "Up" to be in
> > the header. You seem to have done all the substantive changes to
> > stylesheet.dsl --- would you make these changes? Thanks.
> >
> > and from March 11:
> >
> > OK, so here is a summary:
> >
> > o remove fast forward/backward links
> > o add book title where there is no heading
> > o make book and chapter titles as links
> > o make the bottom footer match the top header
> >
> > Not sure which suggestion you want but anything that adds "Up"
> > functionality, either with the "Up" literal or the chapter title that is
> > "up" would be an improvement.
>
> Yes, but where do you want the "Up" placed?
>
> Take a random page, such as this one:
> http://developer.postgresql.org/pgdocs/postgres/queries-table-expressions.html
>
> Where should the "Up" at the top go?
In that case, the text "Chapter 7. Queries" should be click-able and act
as "up". If you want to put "(Up)" after the title, that's fine too.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 23+ messages in thread
* Documentation Suggestion
@ 2022-04-28 19:11 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 23+ messages in thread
From: PG Doc comments form @ 2022-04-28 19:11 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: jhebert@micron.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/11/app-initdb.html
Description:
Reference: https://www.postgresql.org/docs/11/app-initdb.html
When installing recently I found the "-A " option of the initdb command only
accepts lowercase argument. For example "-A LDAP" is not valid and must be
"-A ldap" otherwise the following error is returned:
initdb: invalid authentication method "LDAP" for "local" connections
It may be worth adding a note to the above documentation that states all
option values must be specified in lowercase.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-04-28 20:15 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 23+ messages in thread
From: David G. Johnston @ 2022-04-28 20:15 UTC (permalink / raw)
To: jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Thu, Apr 28, 2022 at 12:36 PM PG Doc comments form <
noreply@postgresql.org> wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/11/app-initdb.html
> Description:
>
> Reference: https://www.postgresql.org/docs/11/app-initdb.html
>
> When installing recently I found the "-A " option of the initdb command
> only
> accepts lowercase argument. For example "-A LDAP" is not valid and must be
> "-A ldap" otherwise the following error is returned:
> initdb: invalid authentication method "LDAP" for "local" connections
>
> It may be worth adding a note to the above documentation that states all
> option values must be specified in lowercase.
>
The -A option will accept any of the option names that are specified in the
documentation for pg_hba.conf
It just so happens that all of those names, at present, consist of all
lower-case characters.
That matching is case-sensitive is not specifically stated but is the
default unless otherwise stated.
The page could use a hyperlink/cross-reference to the pg_hba.conf
documentation.
But we don't go out of our way anywhere else to be so explicit about this
kind of requirement and don't see a point of making this instance an
exception.
David J.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-04-29 09:09 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 2 replies; 23+ messages in thread
From: Alvaro Herrera @ 2022-04-29 09:09 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On 2022-Apr-28, David G. Johnston wrote:
> But we don't go out of our way anywhere else to be so explicit about this
> kind of requirement and don't see a point of making this instance an
> exception.
Maybe we could add a <para> in the Options section before the item list,
along the lines of "be mindful that arguments to options --auth,
--auth-local, --encoding, --locale (and all --lc-* options) are
case-sensitive".
(The point here, I suppose, is that LDAP being an acronym is typically
spelled uppercase, so our use of lowercase is a bit odd.)
Maybe there are other places where this is relevant as well?
> The page could use a hyperlink/cross-reference to the pg_hba.conf
> documentation.
That's easily fixed. How about the attached patch?
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"El destino baraja y nosotros jugamos" (A. Schopenhauer)
Attachments:
[text/x-diff] 0001-case-sensitivity-note-in-initdb.patch (0B, ../../202204290909.nuwx32e3jtjh@alvherre.pgsql/2-0001-case-sensitivity-note-in-initdb.patch)
download
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-04-29 09:52 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
1 sibling, 0 replies; 23+ messages in thread
From: Peter Eisentraut @ 2022-04-29 09:52 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On 29.04.22 11:09, Alvaro Herrera wrote:
> + <para>
> + Be mindful that arguments to options <option>--auth</option>,
> + <option>--auth-local</option>, <option>--encoding</option>,
> + <option>--locale</option> (and all <option>--lc-*</option> options) are
> + case-sensitive.
> + </para>
Almost all arguments of command-line options of all PostgreSQL tools are
case-sensitive. Consider the initdb -U option for example. By pointing
out a couple of specific cases, wouldn't we also create more confusion
about options not mentioned?
(I'm not sure about the case-sensitivity of the locale options. That
could be OS-dependent.)
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-04-29 14:06 Tom Lane <tgl@sss.pgh.pa.us>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
1 sibling, 2 replies; 23+ messages in thread
From: Tom Lane @ 2022-04-29 14:06 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> On 2022-Apr-28, David G. Johnston wrote:
>> But we don't go out of our way anywhere else to be so explicit about this
>> kind of requirement and don't see a point of making this instance an
>> exception.
> Maybe we could add a <para> in the Options section before the item list,
> along the lines of "be mindful that arguments to options --auth,
> --auth-local, --encoding, --locale (and all --lc-* options) are
> case-sensitive".
I don't think this is an improvement, mainly for the reason David
mentions: why wouldn't you need a similar statement on every single
one of our program man pages?
>> The page could use a hyperlink/cross-reference to the pg_hba.conf
>> documentation.
> That's easily fixed. How about the attached patch?
That part's OK, but personally I'd only have cited the link once.
regards, tom lane
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-04-29 15:05 David G. Johnston <david.g.johnston@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 23+ messages in thread
From: David G. Johnston @ 2022-04-29 15:05 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Alvaro Herrera <alvherre@alvh.no-ip.org>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Fri, Apr 29, 2022 at 7:07 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> > On 2022-Apr-28, David G. Johnston wrote:
>
> >> The page could use a hyperlink/cross-reference to the pg_hba.conf
> >> documentation.
>
> > That's easily fixed. How about the attached patch?
>
> That part's OK, but personally I'd only have cited the link once.
>
>
Agreed, one or three, including the local-only option but ignoring the
host-only one seems like a mistake.
I would just document the -A/--auth-method option, the other two are close
enough in space to borrow it just fine.
Shall we do a return link from the pg_hba.conf to initdb? The first
paragraph already has:
"A default pg_hba.conf file is installed when the data directory is
initialized by initdb."
David J.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-05-13 18:41 Bruce Momjian <bruce@momjian.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2022-05-13 18:41 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Alvaro Herrera <alvherre@alvh.no-ip.org>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote:
> Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> > On 2022-Apr-28, David G. Johnston wrote:
> >> But we don't go out of our way anywhere else to be so explicit about this
> >> kind of requirement and don't see a point of making this instance an
> >> exception.
>
> > Maybe we could add a <para> in the Options section before the item list,
> > along the lines of "be mindful that arguments to options --auth,
> > --auth-local, --encoding, --locale (and all --lc-* options) are
> > case-sensitive".
>
> I don't think this is an improvement, mainly for the reason David
> mentions: why wouldn't you need a similar statement on every single
> one of our program man pages?
I think the confusion is that while the option arguments are
case-sensitive, many of the values are typically used as all upper-case,
and I think any doc mention would have to include that:
Note that valid --auth option values are all lower case, even
for authentication types that typically appear as all upper case,
e.g., "LDAP".
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-05-14 15:21 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Alvaro Herrera @ 2022-05-14 15:21 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
I pushed the other suggested bits.
On 2022-May-13, Bruce Momjian wrote:
> On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote:
> > I don't think this is an improvement, mainly for the reason David
> > mentions: why wouldn't you need a similar statement on every single
> > one of our program man pages?
>
> I think the confusion is that while the option arguments are
> case-sensitive, many of the values are typically used as all upper-case,
> and I think any doc mention would have to include that:
>
> Note that valid --auth option values are all lower case, even
> for authentication types that typically appear as all upper case,
> e.g., "LDAP".
Yeah, that was my initial thought too. The case-sensitivity is a
consideration for other things too (such as locale or encoding names),
but for those we do match the operating system name exactly, rather than
using our own lower-case version of it, which nobody else uses.
So really the point is not about the fact that it is case sensitive as
that the case of our name doesn't match the usual one. Maybe the note
should be "Note that authentication types are all lower case, [even for
...]" or something like that.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"I can see support will not be a problem. 10 out of 10." (Simon Wittber)
(http://archives.postgresql.org/pgsql-general/2004-12/msg00159.php)
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-05-24 12:36 Bruce Momjian <bruce@momjian.us>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2022-05-24 12:36 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote:
> I pushed the other suggested bits.
>
> On 2022-May-13, Bruce Momjian wrote:
>
> > On Fri, Apr 29, 2022 at 10:06:57AM -0400, Tom Lane wrote:
>
> > > I don't think this is an improvement, mainly for the reason David
> > > mentions: why wouldn't you need a similar statement on every single
> > > one of our program man pages?
> >
> > I think the confusion is that while the option arguments are
> > case-sensitive, many of the values are typically used as all upper-case,
> > and I think any doc mention would have to include that:
> >
> > Note that valid --auth option values are all lower case, even
> > for authentication types that typically appear as all upper case,
> > e.g., "LDAP".
>
> Yeah, that was my initial thought too. The case-sensitivity is a
> consideration for other things too (such as locale or encoding names),
> but for those we do match the operating system name exactly, rather than
> using our own lower-case version of it, which nobody else uses.
>
> So really the point is not about the fact that it is case sensitive as
> that the case of our name doesn't match the usual one. Maybe the note
> should be "Note that authentication types are all lower case, [even for
> ...]" or something like that.
Agreed.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-07-14 22:23 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2022-07-14 22:23 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Tue, May 24, 2022 at 08:36:18AM -0400, Bruce Momjian wrote:
> fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote:
> > On 2022-May-13, Bruce Momjian wrote:
> > > Note that valid --auth option values are all lower case, even
> > > for authentication types that typically appear as all upper case,
> > > e.g., "LDAP".
> >
> > Yeah, that was my initial thought too. The case-sensitivity is a
> > consideration for other things too (such as locale or encoding names),
> > but for those we do match the operating system name exactly, rather than
> > using our own lower-case version of it, which nobody else uses.
> >
> > So really the point is not about the fact that it is case sensitive as
> > that the case of our name doesn't match the usual one. Maybe the note
> > should be "Note that authentication types are all lower case, [even for
> > ...]" or something like that.
Here is a patch that implements this.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
Attachments:
[text/x-diff] auth.diff (745B, ../../YtCXb%2FJ03HBAcHPQ@momjian.us/2-auth.diff)
download | inline diff:
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index b2a459fb0d..433759928b 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -417,7 +417,9 @@ hostnogssenc <replaceable>database</replaceable> <replaceable>user</replaceabl
<para>
Specifies the authentication method to use when a connection matches
this record. The possible choices are summarized here; details
- are in <xref linkend="auth-methods"/>.
+ are in <xref linkend="auth-methods"/>. All the options
+ are lower case and treated case sensitively, so even acronyms like
+ <literal>ldap</literal> must be specified as lower case.
<variablelist>
<varlistentry>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-07-21 17:58 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Bruce Momjian @ 2022-07-21 17:58 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Thu, Jul 14, 2022 at 06:23:43PM -0400, Bruce Momjian wrote:
> On Tue, May 24, 2022 at 08:36:18AM -0400, Bruce Momjian wrote:
> > fOn Sat, May 14, 2022 at 05:21:58PM +0200, Álvaro Herrera wrote:
> > > On 2022-May-13, Bruce Momjian wrote:
> > > > Note that valid --auth option values are all lower case, even
> > > > for authentication types that typically appear as all upper case,
> > > > e.g., "LDAP".
> > >
> > > Yeah, that was my initial thought too. The case-sensitivity is a
> > > consideration for other things too (such as locale or encoding names),
> > > but for those we do match the operating system name exactly, rather than
> > > using our own lower-case version of it, which nobody else uses.
> > >
> > > So really the point is not about the fact that it is case sensitive as
> > > that the case of our name doesn't match the usual one. Maybe the note
> > > should be "Note that authentication types are all lower case, [even for
> > > ...]" or something like that.
>
> Here is a patch that implements this.
Patch applied to all supported branches.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-07-21 18:05 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 23+ messages in thread
From: Alvaro Herrera @ 2022-07-21 18:05 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On 2022-Jul-21, Bruce Momjian wrote:
> Patch applied to all supported branches.
Thanks, looks good.
I notice you credited me as the reporter, but actually the reporter is
jhebert@micron.com.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation Suggestion
@ 2022-07-21 18:43 Bruce Momjian <bruce@momjian.us>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 23+ messages in thread
From: Bruce Momjian @ 2022-07-21 18:43 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; jhebert@micron.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Thu, Jul 21, 2022 at 08:05:49PM +0200, Álvaro Herrera wrote:
> On 2022-Jul-21, Bruce Momjian wrote:
>
> > Patch applied to all supported branches.
>
> Thanks, looks good.
>
> I notice you credited me as the reporter, but actually the reporter is
> jhebert@micron.com.
Oh, my apologies. I had not kept the first email and didn't notice the
"Re:".
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 23+ messages in thread
* [very minor] Documentation suggestion
@ 2022-10-21 02:19 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 23+ messages in thread
From: PG Doc comments form @ 2022-10-21 02:19 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: andyatkinson@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/logicaldecoding-synchronous.html
Description:
Very minor suggestion. Earlier on this page, commands are referred to that
can cause "a deadlock". Later on the page, it says "cause deadlock".
https://www.postgresql.org/account/comments/new/15/logicaldecoding-synchronous.html/
"Note that these commands that can cause deadlock"
I think that may also be grammatically correct, however I thought "a
deadlock" (adding the "a") sounded smoother to me when reading. Suggestion
below (adds "a" before "deadlock").
"Note that these commands that can cause a deadlock"
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: [very minor] Documentation suggestion
@ 2023-10-27 15:40 Bruce Momjian <bruce@momjian.us>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 0 replies; 23+ messages in thread
From: Bruce Momjian @ 2023-10-27 15:40 UTC (permalink / raw)
To: andyatkinson@gmail.com; pgsql-docs@lists.postgresql.org
On Fri, Oct 21, 2022 at 02:19:12AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/15/logicaldecoding-synchronous.html
> Description:
>
> Very minor suggestion. Earlier on this page, commands are referred to that
> can cause "a deadlock". Later on the page, it says "cause deadlock".
>
> https://www.postgresql.org/account/comments/new/15/logicaldecoding-synchronous.html/
>
> "Note that these commands that can cause deadlock"
The full sentence is:
Note that these commands that can cause deadlock apply to not only
explicitly indicated system catalog tables above but also to any other
[user] catalog table.
What I think it means is:
Note that these commands, that can cause deadlock, apply to not only
explicitly indicated system catalog tables above but also to any other
[user] catalog table.
so with "a" it would be:
Note that these commands, that can cause a deadlock, apply to not only
explicitly indicated system catalog tables above but also to any other
[user] catalog table.
but it still needs help ;-) Here is the text I just applied:
Note that these commands can cause deadlocks not only for the system
catalog tables listed above but for other catalog tables.
Attached is the applied patch to master.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
[text/x-diff] master.diff (992B, ../../ZTvZ2JGcoKoFxMUB@momjian.us/2-master.diff)
download | inline diff:
commit 16ace6f745
Author: Bruce Momjian <bruce@momjian.us>
Date: Fri Oct 27 11:35:47 2023 -0400
doc: clarify logical decoding's deadlock of system tables
Reported-by: andyatkinson@gmail.com
Discussion: https://postgr.es/m/166631875298.630.2861049399528658047@wrigleys.postgresql.org
Backpatch-through: master
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 5af016cfa9..8067946a25 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -1197,9 +1197,8 @@ OutputPluginWrite(ctx, true);
</listitem>
</itemizedlist>
- Note that these commands that can cause deadlock apply to not only explicitly
- indicated system catalog tables above but also to any other [user] catalog
- table.
+ Note that these commands can cause deadlocks not only for the system
+ catalog tables listed above but for other catalog tables.
</para>
</sect2>
</sect1>
^ permalink raw reply [nested|flat] 23+ messages in thread
end of thread, other threads:[~2023-10-27 15:40 UTC | newest]
Thread overview: 23+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2011-08-23 22:57 documentation suggestion Rob Sargent <robjsargent@gmail.com>
2011-08-24 03:45 ` Bruce Momjian <bruce@momjian.us>
2011-08-24 04:55 ` Rob Sargent <robjsargent@gmail.com>
2011-08-24 12:33 ` Bruce Momjian <bruce@momjian.us>
2011-08-24 18:59 ` Peter Eisentraut <peter_e@gmx.net>
2011-08-25 03:40 ` Bruce Momjian <bruce@momjian.us>
2011-08-27 20:34 ` Peter Eisentraut <peter_e@gmx.net>
2011-09-01 11:53 ` Bruce Momjian <bruce@momjian.us>
2022-04-28 19:11 Documentation Suggestion PG Doc comments form <noreply@postgresql.org>
2022-04-28 20:15 ` Re: Documentation Suggestion David G. Johnston <david.g.johnston@gmail.com>
2022-04-29 09:09 ` Re: Documentation Suggestion Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-04-29 09:52 ` Re: Documentation Suggestion Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2022-04-29 14:06 ` Re: Documentation Suggestion Tom Lane <tgl@sss.pgh.pa.us>
2022-04-29 15:05 ` Re: Documentation Suggestion David G. Johnston <david.g.johnston@gmail.com>
2022-05-13 18:41 ` Re: Documentation Suggestion Bruce Momjian <bruce@momjian.us>
2022-05-14 15:21 ` Re: Documentation Suggestion Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-05-24 12:36 ` Re: Documentation Suggestion Bruce Momjian <bruce@momjian.us>
2022-07-14 22:23 ` Re: Documentation Suggestion Bruce Momjian <bruce@momjian.us>
2022-07-21 17:58 ` Re: Documentation Suggestion Bruce Momjian <bruce@momjian.us>
2022-07-21 18:05 ` Re: Documentation Suggestion Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-07-21 18:43 ` Re: Documentation Suggestion Bruce Momjian <bruce@momjian.us>
2022-10-21 02:19 [very minor] Documentation suggestion PG Doc comments form <noreply@postgresql.org>
2023-10-27 15:40 ` Re: [very minor] Documentation suggestion 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