Re: "IS NOT DOCUMENT" is missing

[Bruce Momjian]

On Fri, Mar 16, 2018 at 01:56:32AM -0300, Euler Taveira wrote:
> 2018-03-09 0:10 GMT-03:00 PG Doc comments form :
> > From testing, it seems like PostgreSQL supports the syntax "IS NOT DOCUMENT"
> > in addition to "IS DOCUMENT", similar to "IS NOT NULL", "IS NOT FALSE", etc,
> > however this does not appear to be documented, only "IS DOCUMENT" is.
> >
> It has been like that since day 1. I'm not sure why it was not
> documented. It already has some tests. I'll bet that was an oversight.
> Should we repeat the statement in another item (like the attached
> patch)? Another option is to add a statement in the "IS DOCUMENT"
> item. I'm afraid that NULL return wouldn't be clear.
> 

Patch applied and backpatched to Postgres 10.  Thank.s

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+  Ancient Roman grave inscription +

Re: Documentation for varbit is missing size parameter

[Bruce Momjian]

On Fri, Mar 16, 2018 at 01:17:04AM -0300, Euler Taveira wrote:
> 2018-03-11 1:43 GMT-03:00 PG Doc comments form :
> > The documentation for the varbit data type is missing the size parameter "[
> > (n) ]".
> >
> Good catch! It seems to be an oversight in commit
> 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds it.

Wow, that commit is from 2004.  Patch applied and backpatched to v10.

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+  Ancient Roman grave inscription +

Re: Documentation for varbit is missing size parameter

[Magnus Hagander]

On Fri, Mar 30, 2018 at 5:18 PM, Bruce Momjian  wrote:

> On Fri, Mar 16, 2018 at 01:17:04AM -0300, Euler Taveira wrote:
> > 2018-03-11 1:43 GMT-03:00 PG Doc comments form :
> > > The documentation for the varbit data type is missing the size
> parameter "[
> > > (n) ]".
> > >
> > Good catch! It seems to be an oversight in commit
> > 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds it.
>
> Wow, that commit is from 2004.  Patch applied and backpatched to v10.
>

If it goes all the way back to 2004, why not backpatch further?

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Documentation for varbit is missing size parameter

[Bruce Momjian]

On Fri, Mar 30, 2018 at 05:39:46PM +0200, Magnus Hagander wrote:
> On Fri, Mar 30, 2018 at 5:18 PM, Bruce Momjian  wrote:
> 
> On Fri, Mar 16, 2018 at 01:17:04AM -0300, Euler Taveira wrote:
> > 2018-03-11 1:43 GMT-03:00 PG Doc comments form :
> > > The documentation for the varbit data type is missing the size
> parameter "[
> > > (n) ]".
> > >
> > Good catch! It seems to be an oversight in commit
> > 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds it.
> 
> Wow, that commit is from 2004.  Patch applied and backpatched to v10.
> 
> 
> If it goes all the way back to 2004, why not backpatch further?

Uh, I am always debating how important it is to backpatck vs the churn
we require of translations of our docs.  In this case, it didn't seem
worthwhile to have all of those translations try to deal with this
change for all those back branches.

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+  Ancient Roman grave inscription +

Re: Documentation for varbit is missing size parameter

[Magnus Hagander]

On Fri, Mar 30, 2018 at 6:26 PM, Bruce Momjian  wrote:

> On Fri, Mar 30, 2018 at 05:39:46PM +0200, Magnus Hagander wrote:
> > On Fri, Mar 30, 2018 at 5:18 PM, Bruce Momjian  wrote:
> >
> > On Fri, Mar 16, 2018 at 01:17:04AM -0300, Euler Taveira wrote:
> > > 2018-03-11 1:43 GMT-03:00 PG Doc comments form <
> nore...@postgresql.org>:
> > > > The documentation for the varbit data type is missing the size
> > parameter "[
> > > > (n) ]".
> > > >
> > > Good catch! It seems to be an oversight in commit
> > > 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds
> it.
> >
> > Wow, that commit is from 2004.  Patch applied and backpatched to v10.
> >
> >
> > If it goes all the way back to 2004, why not backpatch further?
>
> Uh, I am always debating how important it is to backpatck vs the churn
> we require of translations of our docs.  In this case, it didn't seem
> worthwhile to have all of those translations try to deal with this
> change for all those back branches.
>
>
If it's a clean backpatch I'd say it is -- people who are using PostgreSQL
9.6 will be reading the documentation for 9.6 etc, so they will not know
about the fix then.

If it's not a clean backpatch I can certainly see considering it, but if
it's not a lot of effort then I'd say it's definitely worth it.

I really don't think considerations for translators of the *docs* are an
issue here. If you don't backpatch it, then nobody gets the fix. If you
backpatch it, then English readers do get the fix, and translated docs
readers *might* get the fix, depending on how they are maintained. It's not
like translatable strings where if they change in a backbranch they will
revert to English unless the translation is updated -- for the docs, they
just don't get the fix.


-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Documentation for varbit is missing size parameter

[Bruce Momjian]

On Fri, Mar 30, 2018 at 06:28:15PM +0200, Magnus Hagander wrote:
> On Fri, Mar 30, 2018 at 6:26 PM, Bruce Momjian  wrote:
> Uh, I am always debating how important it is to backpatck vs the churn
> we require of translations of our docs.  In this case, it didn't seem
> worthwhile to have all of those translations try to deal with this
> change for all those back branches.

> If it's a clean backpatch I'd say it is -- people who are using PostgreSQL 9.6
> will be reading the documentation for 9.6 etc, so they will not know about the
> fix then.
> 
> If it's not a clean backpatch I can certainly see considering it, but if it's
> not a lot of effort then I'd say it's definitely worth it.
> 
> I really don't think considerations for translators of the *docs* are an issue
> here. If you don't backpatch it, then nobody gets the fix. If you backpatch 
> it,
> then English readers do get the fix, and translated docs readers *might* get
> the fix, depending on how they are maintained. It's not like translatable
> strings where if they change in a backbranch they will revert to English 
> unless
> the translation is updated -- for the docs, they just don't get the fix. 

My logic is that the more we backpatch, the less likely translators are
going to be to keep their docs up-to-date with minor releases since the
minor release diff is larger and contains more items that aren't
_required_ for correctness.

I looked at this patch and thought it was more a stylistic item rather
than a correction.  Is that right?

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+  Ancient Roman grave inscription +

Re: Documentation for varbit is missing size parameter

[David G. Johnston]

On Friday, March 30, 2018, Bruce Momjian  wrote:
>
> I looked at this patch and thought it was more a stylistic item rather
> than a correction.  Is that right?
>

Looks like a syntax bug fix to me - especially since it is a reference
table.  Those should be back-patched.

David J.

Re: Documentation for varbit is missing size parameter

[Bruce Momjian]

On Fri, Mar 30, 2018 at 10:31:07AM -0700, David G. Johnston wrote:
> On Friday, March 30, 2018, Bruce Momjian  wrote:
> 
> I looked at this patch and thought it was more a stylistic item rather
> than a correction.  Is that right?
> 
> 
> Looks like a syntax bug fix to me - especially since it is a reference table. 
> Those should be back-patched.

OK, now backpatched through 9.3.

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+  Ancient Roman grave inscription +