MIME-Version: 1.0
In-Reply-To: <157301068439.14260.3440469821975939421@wrigleys.postgresql.org>
References: <157301068439.14260.3440469821975939421@wrigleys.postgresql.org>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Wed, 6 Nov 2019 07:12:17 -0700
Message-ID: 
 <CAKFQuwbxV27-WBz3b8QxbcrBAEXuvqmEWUM2eA8MAeHnwC6d=A@mail.gmail.com>
Subject: Re: Adding a Column documentation is misleading
To: "gavinflower@archidevsys.co.nz" <gavinflower@archidevsys.co.nz>,
	"pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Content-Type: multipart/alternative; boundary="000000000000ebba930596ae2286"
Precedence: bulk

--000000000000ebba930596ae2286
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tuesday, November 5, 2019, PG Doc comments form <noreply@postgresql.org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/ddl-alter.html
> Description:
>
> In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE produc=
ts
> ADD COLUMN description text;'
>
> The words 'description' and 'text' are misleading -- as according to the
> formal documentation of the SQL command
> (https://www.postgresql.org/docs/12/sql-altertable.html), they should be
> 'column_name' and 'data_type'.
>
> A similar problem exists for removing a column, and other actions.
>

Chapter 5 is tutorial-like and uses actual meaningful names instead of
syntax placeholders.  I don=E2=80=99t really see a problem aside from maybe=
 a
different example name could be chosen.  Making it column_name isn=E2=80=99=
t an
improvement.

David J.

--000000000000ebba930596ae2286
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tuesday, November 5, 2019, PG Doc comments form &lt;<a href=3D"mailto:no=
reply@postgresql.org">noreply@postgresql.org</a>&gt; wrote:<br><blockquote =
class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid=
;padding-left:1ex">The following documentation comment has been logged on t=
he website:<br>
<br>
Page: <a href=3D"https://www.postgresql.org/docs/12/ddl-alter.html" target=
=3D"_blank">https://www.postgresql.org/<wbr>docs/12/ddl-alter.html</a><br>
Description:<br>
<br>
In 5.6.1. Adding a Column, there is a kind of example &#39;ALTER TABLE prod=
ucts<br>
ADD COLUMN description text;&#39;<br>
<br>
The words &#39;description&#39; and &#39;text&#39; are misleading -- as acc=
ording to the<br>
formal documentation of the SQL command<br>
(<a href=3D"https://www.postgresql.org/docs/12/sql-altertable.html" target=
=3D"_blank">https://www.postgresql.org/<wbr>docs/12/sql-altertable.html</a>=
), they should be<br>
&#39;column_name&#39; and &#39;data_type&#39;.<br>
<br>
A similar problem exists for removing a column, and other actions.<br>
</blockquote><div><br></div><div>Chapter 5 is tutorial-like and uses actual=
 meaningful names instead of syntax placeholders.=C2=A0 I don=E2=80=99t rea=
lly see a problem aside from maybe a different example name could be chosen=
.=C2=A0 Making it column_name isn=E2=80=99t an improvement.</div><div><br><=
/div><div>David J.=C2=A0</div>

--000000000000ebba930596ae2286--