Thread: boolean and bool in documentation

boolean and bool in documentation

From

Masahiko Sawada

Date:

18 February 2019, 18:56:19

HI,

I realized that 'boolean' and 'bool' are mixed as SQL data type in the
documentation. Here is the quick check result;

$ git grep -c "<type>bool</type>" doc
doc/src/sgml/bki.sgml:1
doc/src/sgml/btree-gin.sgml:1
doc/src/sgml/catalogs.sgml:88
doc/src/sgml/datatype.sgml:1
doc/src/sgml/ecpg.sgml:2
doc/src/sgml/func.sgml:20
doc/src/sgml/gin.sgml:2
doc/src/sgml/monitoring.sgml:1
doc/src/sgml/plpython.sgml:1
doc/src/sgml/xfunc.sgml:1
doc/src/sgml/xml2.sgml:2

 $ git grep -c "<type>boolean</type>" doc
doc/src/sgml/adminpack.sgml:2
doc/src/sgml/auto-explain.sgml:6
doc/src/sgml/catalogs.sgml:23
doc/src/sgml/config.sgml:93
doc/src/sgml/cube.sgml:10
doc/src/sgml/datatype.sgml:7
doc/src/sgml/ecpg.sgml:2
doc/src/sgml/extend.sgml:2
doc/src/sgml/func.sgml:102
doc/src/sgml/hstore.sgml:2
doc/src/sgml/information_schema.sgml:1
doc/src/sgml/intarray.sgml:5
doc/src/sgml/isn.sgml:3
doc/src/sgml/json.sgml:2
doc/src/sgml/ltree.sgml:18
doc/src/sgml/monitoring.sgml:2
doc/src/sgml/pgbuffercache.sgml:1
doc/src/sgml/pgprewarm.sgml:1
doc/src/sgml/pgrowlocks.sgml:1
doc/src/sgml/pgstatstatements.sgml:2
doc/src/sgml/pgtrgm.sgml:5
doc/src/sgml/plperl.sgml:1
doc/src/sgml/plpgsql.sgml:1
doc/src/sgml/plpython.sgml:2
doc/src/sgml/queries.sgml:1
doc/src/sgml/ref/alter_subscription.sgml:2
doc/src/sgml/ref/alter_view.sgml:1
doc/src/sgml/ref/copy.sgml:1
doc/src/sgml/ref/create_cast.sgml:1
doc/src/sgml/ref/create_policy.sgml:2
doc/src/sgml/ref/create_rule.sgml:1
doc/src/sgml/ref/create_subscription.sgml:4
doc/src/sgml/ref/create_table.sgml:2
doc/src/sgml/ref/create_type.sgml:1
doc/src/sgml/ref/create_view.sgml:1
doc/src/sgml/ref/delete.sgml:1
doc/src/sgml/ref/insert.sgml:1
doc/src/sgml/ref/select.sgml:2
doc/src/sgml/ref/update.sgml:1
doc/src/sgml/sepgsql.sgml:2
doc/src/sgml/spgist.sgml:1
doc/src/sgml/syntax.sgml:1
doc/src/sgml/typeconv.sgml:2
doc/src/sgml/xfunc.sgml:1
doc/src/sgml/xindex.sgml:1
doc/src/sgml/xoper.sgml:2

AFAICS there seems not to be explicit rules and policies for usage of
'boolean' and 'bool'. We use 'bool' for colum data type of almost
system catalogs but use 'boolean' for some catalogs (pg_pltemplate and
pg_policy). The same is true for functions and system views. Is it
better to unify them into 'boolean' for consistency and so as not
unnecessarily confuse users? FYI the name of boolean type is 'boolean'
in the standard.

Regards,

--
Masahiko Sawada
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center

Re: boolean and bool in documentation

From

Bruce Momjian

Date:

22 February 2019, 03:13:13

On Tue, Feb 19, 2019 at 12:56:19AM +0900, Masahiko Sawada wrote:
> AFAICS there seems not to be explicit rules and policies for usage of
> 'boolean' and 'bool'. We use 'bool' for colum data type of almost
> system catalogs but use 'boolean' for some catalogs (pg_pltemplate and
> pg_policy). The same is true for functions and system views. Is it
> better to unify them into 'boolean' for consistency and so as not
> unnecessarily confuse users? FYI the name of boolean type is 'boolean'
> in the standard.

Yes, I think so.

-- 
  Bruce Momjian  <bruce@momjian.us>        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: boolean and bool in documentation

From

Tom Lane

Date:

22 February 2019, 03:30:49

Bruce Momjian <bruce@momjian.us> writes:
> On Tue, Feb 19, 2019 at 12:56:19AM +0900, Masahiko Sawada wrote:
>> AFAICS there seems not to be explicit rules and policies for usage of
>> 'boolean' and 'bool'. We use 'bool' for colum data type of almost
>> system catalogs but use 'boolean' for some catalogs (pg_pltemplate and
>> pg_policy). The same is true for functions and system views. Is it
>> better to unify them into 'boolean' for consistency and so as not
>> unnecessarily confuse users? FYI the name of boolean type is 'boolean'
>> in the standard.

> Yes, I think so.

FWIW, I'm not excited about this.  We accept "bool" and "boolean"
interchangeably, and it does not seem like an improvement for the
docs to use only one form.  By that argument, somebody should go
through the docs and nuke every usage of "::" in favor of
SQL-standard CAST(...) notation, every usage of "float8"
in favor of DOUBLE PRECISION, every usage of "timestamptz" in
favor of the long form, etc etc.

            regards, tom lane

Re: boolean and bool in documentation

From

Robert Haas

Date:

22 February 2019, 18:26:44

On Thu, Feb 21, 2019 at 7:31 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> FWIW, I'm not excited about this.  We accept "bool" and "boolean"
> interchangeably, and it does not seem like an improvement for the
> docs to use only one form.  By that argument, somebody should go
> through the docs and nuke every usage of "::" in favor of
> SQL-standard CAST(...) notation, every usage of "float8"
> in favor of DOUBLE PRECISION, every usage of "timestamptz" in
> favor of the long form, etc etc.

I'm not terribly excited about it either, but mostly because it seems
like a lot of churn for a minimal gain, and it'll be consistent for
about 6 months before somebody re-introduces a conflicting usage.  I
do not, on the other hand, believe that there's no point in being
consistent about anything unless we're consistent about everything;
that's a straw man.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Re: boolean and bool in documentation

From

Tom Lane

Date:

22 February 2019, 20:45:55

Robert Haas <robertmhaas@gmail.com> writes:
> On Thu, Feb 21, 2019 at 7:31 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> FWIW, I'm not excited about this.  We accept "bool" and "boolean"
>> interchangeably, and it does not seem like an improvement for the
>> docs to use only one form.  By that argument, somebody should go
>> through the docs and nuke every usage of "::" in favor of
>> SQL-standard CAST(...) notation, every usage of "float8"
>> in favor of DOUBLE PRECISION, every usage of "timestamptz" in
>> favor of the long form, etc etc.

> I'm not terribly excited about it either, but mostly because it seems
> like a lot of churn for a minimal gain, and it'll be consistent for
> about 6 months before somebody re-introduces a conflicting usage.

Yeah, that last is a really good point.

> I do not, on the other hand, believe that there's no point in being
> consistent about anything unless we're consistent about everything;
> that's a straw man.

That wasn't my argument; rather, I was saying that if someone presents
a patch for s/bool/boolean/g and we accept it, then logically we should
also accept patches for any of these other cases as well.  I doubt that
we would, if only because of the carpal-tunnel angle.  Does that mean
our policy is "we'll be consistent as long as it doesn't add too many
characters"?  Ugh.

            regards, tom lane