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@sraoss.co.jp>
Attachments:
doc_excluding.patchtext/x-diff; name=doc_excluding.patchDownload+7-0
On 27 Jun 2018, at 18:02, Yugo Nagata <nagata@sraoss.co.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@yesql.se> wrote:
On 27 Jun 2018, at 18:02, Yugo Nagata <nagata@sraoss.co.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 nativeEnglish
speaker comments on this.
+ If <literal>EXCLUDING</literal> option <literal></literal> is
specifiedThe 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.g.johnston@gmail.com> wrote:
On Thu, Jun 28, 2018 at 3:57 PM, Daniel Gustafsson <daniel@yesql.se> wrote:
Thank you for your reviewing!
I attached the updated patch.
On 27 Jun 2018, at 18:02, Yugo Nagata <nagata@sraoss.co.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 nativeEnglish
speaker comments on this.
+ If <literal>EXCLUDING</literal> option <literal></literal> is
specifiedThe 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@sraoss.co.jp>
Attachments:
doc_excluding_v2.patchtext/x-diff; name=doc_excluding_v2.patchDownload+7-0
On 29 Jun 2018, at 07:56, Yugo Nagata <nagata@sraoss.co.jp> wrote:
On Thu, 28 Jun 2018 16:22:15 -0700
"David G. Johnston" <david.g.johnston@gmail.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@yesql.se> wrote:
On 29 Jun 2018, at 07:56, Yugo Nagata <nagata@sraoss.co.jp> wrote:
On Thu, 28 Jun 2018 16:22:15 -0700
"David G. Johnston" <david.g.johnston@gmail.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@sraoss.co.jp>
Attachments:
doc_excluding_v3.patchtext/x-diff; name=doc_excluding_v3.patchDownload+7-0
On 29 Jun 2018, at 09:14, Yugo Nagata <nagata@sraoss.co.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@yesql.se> wrote:
On 29 Jun 2018, at 09:14, Yugo Nagata <nagata@sraoss.co.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@sraoss.co.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.eisentraut@2ndquadrant.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@yesql.se> writes:
On 29 Jun 2018, at 15:42, Peter Eisentraut <peter.eisentraut@2ndquadrant.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@sss.pgh.pa.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@sss.pgh.pa.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@sss.pgh.pa.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.eisentraut@2ndquadrant.com> wrote:
On 02.07.18 10:38, Daniel Gustafsson wrote:
On 29 Jun 2018, at 18:44, Tom Lane <tgl@sss.pgh.pa.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@sraoss.co.jp>