Document IS DISTINCT FROM in a more obvious place, and add some more

index entries for IS-foo constructs.

2 files changed, 86 insertions, 9 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7e1b488bae7..fb55b1bff72 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.220 2004/10/04 08:15:41 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.221 2004/10/26 22:16:11 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -283,6 +283,18 @@ PostgreSQL documentation
    </para>
 
    <para>
+    <indexterm>
+     <primary>IS NULL</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS NOT NULL</primary>
+    </indexterm>
+    <indexterm>
+     <primary>ISNULL</primary>
+    </indexterm>
+    <indexterm>
+     <primary>NOTNULL</primary>
+    </indexterm>
     To check whether a value is or is not null, use the constructs
 <synopsis>
 <replaceable>expression</replaceable> IS NULL
@@ -305,6 +317,7 @@ PostgreSQL documentation
     behavior conforms to the SQL standard.
    </para>
 
+  <tip>
    <para>
     Some applications may expect that
     <literal><replaceable>expression</replaceable> = NULL</literal>
@@ -318,8 +331,43 @@ PostgreSQL documentation
     the default behavior in <productname>PostgreSQL</productname>
     releases 6.5 through 7.1.
    </para>
+  </tip>
+
+   <para>
+    <indexterm>
+     <primary>IS DISTINCT FROM</primary>
+    </indexterm>
+    The ordinary comparison operators yield null (signifying <quote>unknown</>)
+    when either input is null.  Another way to do comparisons is with the
+    <literal>IS DISTINCT FROM</literal> construct:
+<synopsis>
+<replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
+</synopsis>
+    For non-null inputs this is the same as the <literal>&lt;&gt;</> operator.
+    However, when both inputs are null it will return false, and when just
+    one input is null it will return true.  Thus it effectively acts as though
+    null were a normal data value, rather than <quote>unknown</>.
+   </para>
 
    <para>
+    <indexterm>
+     <primary>IS TRUE</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS NOT TRUE</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS FALSE</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS NOT FALSE</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS UNKNOWN</primary>
+    </indexterm>
+    <indexterm>
+     <primary>IS NOT UNKNOWN</primary>
+    </indexterm>
     Boolean values can also be tested using the constructs
 <synopsis>
 <replaceable>expression</replaceable> IS TRUE
@@ -329,9 +377,13 @@ PostgreSQL documentation
 <replaceable>expression</replaceable> IS UNKNOWN
 <replaceable>expression</replaceable> IS NOT UNKNOWN
 </synopsis>
-    These are similar to <literal>IS NULL</literal> in that they will
-    always return true or false, never a null value, even when the operand is null.
+    These will always return true or false, never a null value, even when the
+    operand is null.
     A null input is treated as the logical value <quote>unknown</>.
+    Notice that <literal>IS UNKNOWN</> and <literal>IS NOT UNKNOWN</> are
+    effectively the same as <literal>IS NULL</literal> and
+    <literal>IS NOT NULL</literal>, respectively, except that the input
+    expression must be of Boolean type.
    </para>
   </sect1>
 
@@ -7344,7 +7396,7 @@ SELECT col1 FROM tab1
   </sect2>
 
   <sect2>
-   <title><literal>NOT IN </literal></title>
+   <title><literal>NOT IN</literal></title>
 
 <synopsis>
 <replaceable>expression</replaceable> NOT IN (<replaceable>subquery</replaceable>)
@@ -7538,9 +7590,9 @@ SELECT col1 FROM tab1
   <sect2>
    <title>Row-wise Comparison</title>
 
-   <indexterm>
+   <indexterm zone="functions-subquery">
     <primary>comparison</primary>
-    <secondary>of rows</secondary>
+    <secondary>subquery result row</secondary>
    </indexterm>
 
 <synopsis>
@@ -7594,6 +7646,23 @@ SELECT col1 FROM tab1
    <primary>SOME</primary>
   </indexterm>
 
+  <indexterm>
+   <primary>comparison</primary>
+   <secondary>row-wise</secondary>
+  </indexterm>
+
+  <indexterm>
+   <primary>IS DISTINCT FROM</primary>
+  </indexterm>
+
+  <indexterm>
+   <primary>IS NULL</primary>
+  </indexterm>
+
+  <indexterm>
+   <primary>IS NOT NULL</primary>
+  </indexterm>
+
   <para>
    This section describes several specialized constructs for making
    multiple comparisons between groups of values.  These forms are
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 98deceb8957..99038b42692 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.95 2004/09/20 22:48:25 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.96 2004/10/26 22:16:12 tgl Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -1421,6 +1421,10 @@ SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)
     <secondary>constructor</secondary>
    </indexterm>
 
+   <indexterm>
+    <primary>ARRAY</primary>
+   </indexterm>
+
    <para>
     An array constructor is an expression that builds an
     array value from values for its member elements.  A simple array
@@ -1521,13 +1525,17 @@ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
     <secondary>constructor</secondary>
    </indexterm>
 
+   <indexterm>
+    <primary>ROW</primary>
+   </indexterm>
+
    <para>
     A row constructor is an expression that builds a row value (also
     called a composite value) from values
     for its member fields.  A row constructor consists of the key word
-    <literal>ROW</literal>, a left parenthesis <literal>(</>, zero or more
+    <literal>ROW</literal>, a left parenthesis, zero or more
     expressions (separated by commas) for the row field values, and finally
-    a right parenthesis <literal>)</>.  For example,
+    a right parenthesis.  For example,
 <programlisting>
 SELECT ROW(1,2.5,'this is a test');
 </programlisting>