Обсуждение: psql's commit df9f599b is not documented
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/11/app-psql.html Description: Hi quit and exit commands have been added to psql starting from psql 11 through this commit df9f599b https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=df9f599bc6f14307252ac75ea1dc997310da5ba6 but it is not documented in psql documentation https://www.postgresql.org/docs/11/app-psql.html . it has been documented in the release note only https://www.postgresql.org/docs/11/release-11.html#id-1.11.6.9.5.10.2 , please check below two lines . Allow quit and exit to exit psql when given with no prior input (Bruce Momjian) Also print hints about how to exit when quit and exit are used alone on a line while the input buffer is not empty. Add a similar hint for help. Thanks, Mohamed Ali .
On Mon, Aug 2, 2021 at 2:58 PM PG Doc comments form <noreply@postgresql.org> wrote:
quit and exit commands have been added to psql starting from psql 11 through
this commit df9f599b
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=df9f599bc6f14307252ac75ea1dc997310da5ba6
but it is not documented in psql documentation
All documented commands begin with a backslash - and indeed \help and \quit are the official ways to get help and to quit psql. While the others exist as a courtesy they are "unofficial" and thus we've chosen to not document them.
David J.
On Mon, Aug 2, 2021 at 03:31:15PM -0700, David G. Johnston wrote: > On Mon, Aug 2, 2021 at 2:58 PM PG Doc comments form <noreply@postgresql.org> > wrote: > > quit and exit commands have been added to psql starting from psql 11 > through > this commit df9f599b > https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h= > df9f599bc6f14307252ac75ea1dc997310da5ba6 > but it is not documented in psql documentation > > > All documented commands begin with a backslash - and indeed \help and \quit are > the official ways to get help and to quit psql. While the others exist as a > courtesy they are "unofficial" and thus we've chosen to not document them. FYI, this was mentioned in the PG 11 release notes: <para> Allow <command>quit</command> and <command>exit</command> to exit <application>psql</application> when given with no prior input (Bruce Momjian) </para> <para> Also print hints about how to exit when <command>quit</command> and <command>exit</command> are used alone on a line while the input buffer is not empty. Add a similar hint for <command>help</command>. </para> </listitem> -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
On Mon, Aug 2, 2021 at 4:10 PM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Aug 2, 2021 at 03:31:15PM -0700, David G. Johnston wrote:
> On Mon, Aug 2, 2021 at 2:58 PM PG Doc comments form <noreply@postgresql.org>
> wrote:
>
> quit and exit commands have been added to psql starting from psql 11
> through
> this commit df9f599b
> https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=
> df9f599bc6f14307252ac75ea1dc997310da5ba6
> but it is not documented in psql documentation
>
>
> All documented commands begin with a backslash - and indeed \help and \quit are
> the official ways to get help and to quit psql. While the others exist as a
> courtesy they are "unofficial" and thus we've chosen to not document them.
FYI, this was mentioned in the PG 11 release notes:
Yes, the OP pointed that out. It seems inconsistent...either we should document the addition both in the release notes and the psql page proper, or neither. Documenting it only in the release notes seems like the worst possible combination (forgetting the release notes and adding it to the documentation proper at least makes it "official").
David J.
On Mon, Aug 2, 2021 at 04:27:01PM -0700, David G. Johnston wrote: > On Mon, Aug 2, 2021 at 4:10 PM Bruce Momjian <bruce@momjian.us> wrote: > > On Mon, Aug 2, 2021 at 03:31:15PM -0700, David G. Johnston wrote: > > On Mon, Aug 2, 2021 at 2:58 PM PG Doc comments form < > noreply@postgresql.org> > > wrote: > > > > quit and exit commands have been added to psql starting from psql 11 > > through > > this commit df9f599b > > https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h= > > df9f599bc6f14307252ac75ea1dc997310da5ba6 > > but it is not documented in psql documentation > > > > > > All documented commands begin with a backslash - and indeed \help and \ > quit are > > the official ways to get help and to quit psql. While the others exist > as a > > courtesy they are "unofficial" and thus we've chosen to not document > them. > > FYI, this was mentioned in the PG 11 release notes: > > > > Yes, the OP pointed that out. It seems inconsistent...either we should > document the addition both in the release notes and the psql page proper, or > neither. Documenting it only in the release notes seems like the worst possible > combination (forgetting the release notes and adding it to the documentation > proper at least makes it "official"). I think we put it in the PG 11 release notes so people who used Postgres previously would know this item is improved, but for new folks, it will just work if they try it, but we don't want to encourage them to try it. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
On Mon, Aug 2, 2021 at 5:03 PM Bruce Momjian <bruce@momjian.us> wrote:
I think we put it in the PG 11 release notes so people who used Postgres
previously would know this item is improved, but for new folks, it will
just work if they try it, but we don't want to encourage them to try it.
And why do we care about informing people those people of this undocumented behavior? It's not like we want to encourage them to use it either.
I stand by my conviction that a release note entry for a user-visible feature requires having documented said feature in the main documentation - and vice-versa.
David J.
On Mon, Aug 2, 2021 at 05:24:14PM -0700, David G. Johnston wrote: > On Mon, Aug 2, 2021 at 5:03 PM Bruce Momjian <bruce@momjian.us> wrote: > > > I think we put it in the PG 11 release notes so people who used Postgres > previously would know this item is improved, but for new folks, it will > just work if they try it, but we don't want to encourage them to try it. > > > > And why do we care about informing people those people of this undocumented > behavior? It's not like we want to encourage them to use it either. > > I stand by my conviction that a release note entry for a user-visible feature > requires having documented said feature in the main documentation - and > vice-versa. We had a long discussion about this in the PG 11 time frame and that was what was decided. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion.
On Mon, 2 Aug 2021 at 20:56, Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Aug 2, 2021 at 05:24:14PM -0700, David G. Johnston wrote:
> On Mon, Aug 2, 2021 at 5:03 PM Bruce Momjian <bruce@momjian.us> wrote:
>
>
> I think we put it in the PG 11 release notes so people who used Postgres
> previously would know this item is improved, but for new folks, it will
> just work if they try it, but we don't want to encourage them to try it.
>
>
>
> And why do we care about informing people those people of this undocumented
> behavior? It's not like we want to encourage them to use it either.
>
> I stand by my conviction that a release note entry for a user-visible feature
> requires having documented said feature in the main documentation - and
> vice-versa.
I would agree. If it's worth coding it's worth documenting. Unless of course the intention is that this is temporary.
I would also argue that putting them in the release notes is not enough. Am I expected to go through the release notes after I don't find it in the documentation ?
Do we have other undocumented features ?
On Tuesday, August 3, 2021, Dave Cramer <davecramer@postgres.rocks> wrote:
I would also argue that putting them in the release notes is not enough. Am I expected to go through the release notes after I don't find it in the documentation ?
No
Do we have other undocumented features ?
Yes, while rare, decisions to not document stuff that works if tried are made and affirmed. The choice to do so here is entirely within the community’s historical precedent as consistent with established norms.
David J.
Dave Cramer <davecramer@postgres.rocks> writes:
> I would agree. If it's worth coding it's worth documenting. Unless of
> course the intention is that this is temporary.
Documenting it would mean committing to keeping it indefinitely,
which I think was exactly what people didn't want to do. It's
a kluge and we might find ourselves backed into a situation where
we have to take it out.
> Do we have other undocumented features ?
Yup. There are plenty of behaviors that are explained in code comments
but not anywhere user-visible. If we tried to document absolutely
everything that someone might be curious about, the manual would be
three times its current size, but not more useful.
regards, tom lane
Greetings, * Tom Lane (tgl@sss.pgh.pa.us) wrote: > Dave Cramer <davecramer@postgres.rocks> writes: > > I would agree. If it's worth coding it's worth documenting. Unless of > > course the intention is that this is temporary. > > Documenting it would mean committing to keeping it indefinitely, > which I think was exactly what people didn't want to do. It's > a kluge and we might find ourselves backed into a situation where > we have to take it out. Given that it's been a while since 11 came out, this argument doesn't seem like it really holds much water. > > Do we have other undocumented features ? > > Yup. There are plenty of behaviors that are explained in code comments > but not anywhere user-visible. If we tried to document absolutely > everything that someone might be curious about, the manual would be > three times its current size, but not more useful. This isn't a deep internal behavior that we're talking about, it's a very user-visible feature and now we're having users discover it and then complain that it's not documented. I tend to agree with the original poster and some others on this thread that it probably should be documented. Across major versions, if we feel the need to for whatever reason, we can take it out even when it's documented. We've certainly done so for other things in the past, I don't see why this should be viewed as special in that regard. Thanks, Stephen