Date: Wed, 20 Dec 2017 22:15:11 -0500
From: Stephen Frost <sfrost@snowman.net>
To: Michael Paquier <michael.paquier@gmail.com>
Cc: lampacz@gmail.com, pgsql-docs@postgresql.org
Subject: Re: Missing column_constraint explanation
Message-ID: <20171221031511.GX4628@tamriel.snowman.net>
References: <20171220090816.25744.72592@wrigleys.postgresql.org>
 <CAB7nPqRgrAuqT-xeEZqtmaT7SToKQrE3Vd+yxigd0xtiy88x9Q@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="1IIbG6N+/RlMHOea"
Content-Disposition: inline
In-Reply-To: 
 <CAB7nPqRgrAuqT-xeEZqtmaT7SToKQrE3Vd+yxigd0xtiy88x9Q@mail.gmail.com>
User-Agent: Mutt/1.5.21 (2010-09-15)
Precedence: bulk


--1IIbG6N+/RlMHOea
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Michael,

* Michael Paquier (michael.paquier@gmail.com) wrote:
> On Wed, Dec 20, 2017 at 6:08 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/9.6/static/sql-altertable.html
> > Description:
> >
> > Missing column_constraint explanation in parameters section
>=20
> Those docs say already that ADD COLUMN follows the same grammar as
> CREATE TABLE, which basically means that there is no need to duplicate
> the same definition in two places. Note that the same thing applies to
> table_constraint.

I actually disagree with this because it means that psql's \h output for
ALTER TABLE references column_constraint but doesn't define it anywhere.

I'd rather see us move in the other direction- let's try to make the \h
output for each command actually stand alone.  There was some progress
made in that direction recently though I don't recall which command it
was for off-hand, but I'd prefer if it was a general rule.

Now, if we could do that in such a way that we avoid having to actually
duplicate the 'source' for these productions into different places in
the documentation, that would be fantastic because it certainly isn't
fun having to find all the places that need to be updated, but I'm not
sure how easy that would be to do (and to make work with how psql's help
is generated...).

Thanks!

Stephen

--1IIbG6N+/RlMHOea
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: Digital signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBCgAGBQJaOyc/AAoJEO1sijiDR2RVrOYP/jCOYuuXYeFQcW3Gi738FX5o
7wn4vdkHOQD4dOu9xNprfahzzd+xvX8uQmDrWNyND6qFOfMR6flpZJg6v/2yMOvx
ijicCNWa4UWAF86IqMeZRQOrJ9uYx7nF9mhODX3gOkFzR0B0AO5c6xFfLYWivqmx
3fVlSdkQKJB3Ey5aI71LpdpRoFHlhMd08BTus0Gi1D0z6YeG8Lp+y77zwrzXBD+Z
qn89UxmVtwnTzCX1Qc6y7+AnjOF/MT3TxyF6nUPkCwt9ILDC7E6MGpx9urQ6BCvv
XRlTQd3nA6CLxFIT16S58RxMOiab4VBoQ88c6CBkjTgp7eatHcDJsJu9s4F1GJMs
IyD8LjRJgRxpq3l0KeodP9AdvBnFVq/9ys9t3sHrkFcG8QkYwzku/Hkzf4ipU5mZ
kMA29rQNZXoq0Vop6IrXJ4IIclwmJN7Lrwh3n0sosOI/Yf0Dvcq5FpdzTz9K3ajy
cFKfhDT1/20ER3LLhZ6YkhX4PSMN2aptpTpxDudXs+r7Cuv2oeuPLJQEYvZzF7yY
nUfDsaatzLUHIkq5y/1er72z7cHnqOWd3nd0nMTOYz5Bcwvt2uhTacWQin/2izHn
eQyTE5iUvAKyHMkDvi/IktNdDJRXJtCBulksCt7CLQDqd31LD4ztYfsxu3IeeXHB
KyFMPGbuzrMT+CRii1+E
=0Y3x
-----END PGP SIGNATURE-----

--1IIbG6N+/RlMHOea--