CREATE TABLE .. LIKE .. EXCLUDING documentation

Hi,

I found that there isn't explanation about EXCLUDING in CREATE TABLE doc.
Attached is a patch to add this. I would appreciate it if a native English
speaker comments on this.

Regards,

--
Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp>

> On 27 Jun 2018, at 18:02, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:

> I found that there isn't explanation about EXCLUDING in CREATE TABLE doc.
> Attached is a patch to add this. I would appreciate it if a native English
> speaker comments on this.

+ If <literal>EXCLUDING</literal> option <literal></literal> is specified

The empty <literal></literal> seems wrong.

+ after <literal>INCLUDING</literal> options, the specified thing is excluded

“thing” sounds a bit vague here (and in the last sentence as well), but I’m
also not sure what to use instead. “referenced objects" perhaps?

+1 on documenting the EXCLUDING option though.

cheers ./daniel

On Thu, Jun 28, 2018 at 3:57 PM, Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:

> > On 27 Jun 2018, at 18:02, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:
>
> > I found that there isn't explanation about EXCLUDING in CREATE TABLE doc.
> > Attached is a patch to add this. I would appreciate it if a native
> English
> > speaker comments on this.
>
> + If <literal>EXCLUDING</literal> option <literal></literal> is
> specified
>
> The empty <literal></literal> seems wrong.
>
> + after <literal>INCLUDING</literal> options, the specified thing is
> excluded
>
> “thing” sounds a bit vague here (and in the last sentence as well), but I’m
> also not sure what to use instead. “referenced objects" perhaps?
>
> +1 on documenting the EXCLUDING option though.
>

​"is excluded" and "not copied" are redundant to each other and the first
sentence is basically redundant with the second.

​Maybe try something like:

It is legal to specify the same option multiple times - e.g., "INCLUDING
option EXCLUDING option" - the outcome is whichever comes last in the
command (i.e., in the example, option is excluded).

David J.

On Thu, 28 Jun 2018 16:22:15 -0700
"David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Thu, Jun 28, 2018 at 3:57 PM, Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:

Thank you for your reviewing!

I attached the updated patch.

>
> > > On 27 Jun 2018, at 18:02, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:
> >
> > > I found that there isn't explanation about EXCLUDING in CREATE TABLE doc.
> > > Attached is a patch to add this. I would appreciate it if a native
> > English
> > > speaker comments on this.
> >
> > + If <literal>EXCLUDING</literal> option <literal></literal> is
> > specified
> >
> > The empty <literal></literal> seems wrong.

Fixed

> >
> > + after <literal>INCLUDING</literal> options, the specified thing is
> > excluded
> >
> > “thing” sounds a bit vague here (and in the last sentence as well), but I’m
> > also not sure what to use instead. “referenced objects" perhaps?

Fixed.

> >
> > +1 on documenting the EXCLUDING option though.
> >
>
> ​"is excluded" and "not copied" are redundant to each other and the first

I removed "is excluded".

> sentence is basically redundant with the second.
>
> ​Maybe try something like:
>
> It is legal to specify the same option multiple times - e.g., "INCLUDING
> option EXCLUDING option" - the outcome is whichever comes last in the
> command (i.e., in the example, option is excluded).

Certainly. However, it seems to me that example is also redundant.
I rewrote this as follows:

It is legal to specify multiple options for the same kind of object.
If they conflict, latter options always override former options.

Does this make sense?

>
> David J.

--
Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp>

> On 29 Jun 2018, at 07:56, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:
> On Thu, 28 Jun 2018 16:22:15 -0700
> "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

>> ​Maybe try something like:
>>
>> It is legal to specify the same option multiple times - e.g., "INCLUDING
>> option EXCLUDING option" - the outcome is whichever comes last in the
>> command (i.e., in the example, option is excluded).
>
> Certainly. However, it seems to me that example is also redundant.
> I rewrote this as follows:
>
> It is legal to specify multiple options for the same kind of object.
> If they conflict, latter options always override former options.
>
> Does this make sense?

I think this wording makes sense and is clear. Only found a small typo:

+ This is tipically used after <literal>INCLUDING ALL</literal>.

s/tipically/typically/

cheers ./daniel

On Fri, 29 Jun 2018 08:39:01 +0200
Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:

> > On 29 Jun 2018, at 07:56, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:
> > On Thu, 28 Jun 2018 16:22:15 -0700
> > "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> >> ​Maybe try something like:
> >>
> >> It is legal to specify the same option multiple times - e.g., "INCLUDING
> >> option EXCLUDING option" - the outcome is whichever comes last in the
> >> command (i.e., in the example, option is excluded).
> >
> > Certainly. However, it seems to me that example is also redundant.
> > I rewrote this as follows:
> >
> > It is legal to specify multiple options for the same kind of object.
> > If they conflict, latter options always override former options.
> >
> > Does this make sense?
>
> I think this wording makes sense and is clear. Only found a small typo:
>
> + This is tipically used after <literal>INCLUDING ALL</literal>.
>
> s/tipically/typically/

Thanks a lot.

I updated the patch.

>
> cheers ./daniel

--
Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp>

> On 29 Jun 2018, at 09:14, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:

> Thanks a lot.
>
> I updated the patch.

This version looks good to me. You might want to add it to the CF to make sure
it isn’t forgotten.

cheers ./daniel

On Fri, 29 Jun 2018 11:36:19 +0200
Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:

> > On 29 Jun 2018, at 09:14, Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp> wrote:
>
> > Thanks a lot.
> >
> > I updated the patch.
>
> This version looks good to me. You might want to add it to the CF to make sure
> it isn’t forgotten.
>
> cheers ./daniel

Sure. Added.

--
Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp>

While we're here, do people find this useful:

<para>
<literal>INCLUDING ALL</literal> is an abbreviated form of
<literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING
DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS
INCLUDING STORAGE</literal>.
</para>

Maybe something more like "... is an abbreviated form selecting all the
available individual options".

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

> On 29 Jun 2018, at 15:42, Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> wrote:
>
> While we're here, do people find this useful:
>
> <para>
> <literal>INCLUDING ALL</literal> is an abbreviated form of
> <literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING
> DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS
> INCLUDING STORAGE</literal>.
> </para>
>
> Maybe something more like "... is an abbreviated form selecting all the
> available individual options”.

While quite a mouthful, I do find the former quite clear. Your suggestion
clearly reads better, but I would personally scroll back up to the Synopsis to
see the list if it wasn't easily available in the paragraph (but that’s all
personal preference).

cheers ./daniel

Daniel Gustafsson <daniel(at)yesql(dot)se> writes:
>> On 29 Jun 2018, at 15:42, Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> wrote:
>> While we're here, do people find this useful:
>>
>> <para>
>> <literal>INCLUDING ALL</literal> is an abbreviated form of
>> <literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING
>> DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS
>> INCLUDING STORAGE</literal>.
>> </para>
>>
>> Maybe something more like "... is an abbreviated form selecting all the
>> available individual options".

> While quite a mouthful, I do find the former quite clear. Your suggestion
> clearly reads better, but I would personally scroll back up to the Synopsis to
> see the list if it wasn't easily available in the paragraph (but that's all
> personal preference).

+1 for shortening it as proposed by Peter. The existing arrangement
made sense when it was first written, when there were only about three
individual options IIRC. Now it's just confusing, especially since you
can't tell very easily whether any of the individual options were
intentionally omitted from the list. It will not get better with
more options, either.

regards, tom lane

> On 29 Jun 2018, at 18:44, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Now it's just confusing, especially since you
> can't tell very easily whether any of the individual options were
> intentionally omitted from the list. It will not get better with
> more options, either.

Agreed, that’s a good point.

cheers ./daniel

> On 29 Jun 2018, at 18:44, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> +1 for shortening it as proposed by Peter. The existing arrangement
> made sense when it was first written, when there were only about three
> individual options IIRC. Now it's just confusing, especially since you
> can't tell very easily whether any of the individual options were
> intentionally omitted from the list. It will not get better with
> more options, either.

Marking this "Waiting for Author” awaiting an update version expanding with the
above comment.

cheers ./daniel

On 02.07.18 10:38, Daniel Gustafsson wrote:
>> On 29 Jun 2018, at 18:44, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>
>> +1 for shortening it as proposed by Peter. The existing arrangement
>> made sense when it was first written, when there were only about three
>> individual options IIRC. Now it's just confusing, especially since you
>> can't tell very easily whether any of the individual options were
>> intentionally omitted from the list. It will not get better with
>> more options, either.
>
> Marking this "Waiting for Author” awaiting an update version expanding with the
> above comment.

I ended up rewriting that whole section a bit to give it more structure.
I included all the points discussed in this thread.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Wed, 4 Jul 2018 10:46:30 +0200
Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> wrote:

> On 02.07.18 10:38, Daniel Gustafsson wrote:
> >> On 29 Jun 2018, at 18:44, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> >
> >> +1 for shortening it as proposed by Peter. The existing arrangement
> >> made sense when it was first written, when there were only about three
> >> individual options IIRC. Now it's just confusing, especially since you
> >> can't tell very easily whether any of the individual options were
> >> intentionally omitted from the list. It will not get better with
> >> more options, either.
> >
> > Marking this "Waiting for Author” awaiting an update version expanding with the
> > above comment.
>
> I ended up rewriting that whole section a bit to give it more structure.
> I included all the points discussed in this thread.

Thank you for fixing this.

>
> --
> Peter Eisentraut http://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>

--
Yugo Nagata <nagata(at)sraoss(dot)co(dot)jp>