Subject: Documentation for varbit is missing size parameter

From: PG Doc comments form <[email-masked]>
Date: Sun, 11 Mar 2018 04:43:56 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/datatype.html
Description:

The documentation for the varbit data type is missing the size parameter "[
(n) ]".

---

From: Euler Taveira <[email-masked]>
Date: Fri, 16 Mar 2018 01:17:04 -0300

> The documentation for the varbit data type is missing the size parameter "[
Good catch! It seems to be an oversight in commit
768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds it.

-- 
   Euler Taveira                                   Timbira -
http://www.timbira.com.br/
   PostgreSQL: Consultoria, Desenvolvimento, Suporte 24x7 e Treinamento
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 9aa9b28..53059d5 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -60,7 +60,7 @@
 
       <row>
        <entry><type>bit varying [ (<replaceable>n</replaceable>) ]</type></entry>
-       <entry><type>varbit</type></entry>
+       <entry><type>varbit [ (<replaceable>n</replaceable>) ]</type></entry>
        <entry>variable-length bit string</entry>
       </row>

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 30 Mar 2018 11:18:28 -0400

> 768b647ead78d0d63915c1708cad13c2468f9440. The attached patch adds it.

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

-- 
  Bruce Momjian  <[email-masked]>        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 +

---

From: Magnus Hagander <[email-masked]>
Date: Fri, 30 Mar 2018 17:39:46 +0200

> 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/ <http://www.hagander.net/>
 Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 30 Mar 2018 12:26:04 -0400

> 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.

---

From: Magnus Hagander <[email-masked]>
Date: Fri, 30 Mar 2018 18:28:15 +0200

> 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.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 30 Mar 2018 12:34:44 -0400

> 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?

---

From: "David G. Johnston" <[email-masked]>
Date: Fri, 30 Mar 2018 10:31:07 -0700

> 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.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 30 Mar 2018 13:34:25 -0400

On Fri, Mar 30, 2018 at 10:31:07AM -0700, David G. Johnston wrote:
> 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.

---

From: Magnus Hagander <[email-masked]>
Date: Sun, 1 Apr 2018 17:28:32 +0200

> OK, now backpatched through 9.3.
Thanks!