psql's commit df9f599b is not documented

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 ?

Dave Cramer

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