Doc: improve description of allowed spellings for Boolean input.

datatype.sgml failed to explain that boolin() accepts any unique
prefix of the basic input strings.  Indeed it was actively misleading
because it called out a few minimal prefixes without mentioning that
there were more valid inputs.

I also felt that it wasn't doing anybody any favors by conflating
SQL key words, valid Boolean input, and string literals containing
valid Boolean input.  Rewrite in hopes of reducing the confusion.

Per bug #15836 from Yuming Wang, as diagnosed by David Johnston.
Back-patch to supported branches.

Discussion: https://postgr.es/m/15836-656fab055735f511@postgresql.org

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index fc300f605f95515f6b9ee3e37d5fbc6d5c211595..35ecd48ed5d442e5dd43a0db8868d0c0232abc4e 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2905,37 +2905,36 @@ SELECT EXTRACT(days from '80 hours'::interval);
    
 
    
-    Valid literal values for the true state are:
+    Boolean constants can be represented in SQL queries by the SQL
+    key words TRUE, FALSE,
+    and NULL.
+   
+
+   
+    The datatype input function for type boolean accepts these
+    string representations for the true state:
     
-     TRUE
-     't'
-     'true'
-     'y'
-     'yes'
-     'on'
-     '1'
+     true
+     yes
+     on
+     1
     
-    For the false state, the following values can be
-    used:
+    and these representations for the false state:
     
-     FALSE
-     'f'
-     'false'
-     'n'
-     'no'
-     'off'
-     '0'
+     false
+     no
+     off
+     0
     
+    Unique prefixes of these strings are also accepted, for
+    example t or n.
     Leading or trailing whitespace is ignored, and case does not matter.
-    The key words
-    TRUE and FALSE are the preferred
-    (SQL-compliant) usage.
    
 
    
-     shows that
-    boolean values are output using the letters
-    <literal>t and f>.
+    The datatype output function for type boolean always emits
+    either t or f, as shown in
+    <xref linkend="datatype-boolean-example"/>.
    
 
    
@@ -2957,6 +2956,27 @@ SELECT * FROM test1 WHERE a;
  t | sic est
 
    
+
+   
+    The key words TRUE and FALSE are
+    the preferred (SQL-compliant) method for writing
+    Boolean constants in SQL queries.  But you can also use the string
+    representations by following the generic string-literal constant syntax
+    described in , for
+    example 'yes'::boolean.
+   
+
+   
+    Note that the parser automatically understands
+    that TRUE and FALSE are of
+    type boolean, but this is not so
+    for NULL because that can have any type.
+    So in some contexts you might have to cast NULL
+    to boolean explicitly, for
+    example NULL::boolean.  Conversely, the cast can be
+    omitted from a string-literal Boolean value in contexts where the parser
+    can deduce that the literal must be of type boolean.
+