commit fb39d8d2dc798ddd44611e349dedc0a8d41b35c6
Author: David G. Johnston (DU) <davidj@dealeruplift.com>
Date:   Sat Feb 3 00:11:56 2018 +0000

    respose to poc

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5031cd4d70..36e5e482a7 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -15743,10 +15743,10 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
  </sect1>
 
  <sect1 id="functions-schemavar">
-  <title>Functions for access to schema variables</title>
+  <title>Schema Variable Functions</title>
 
   <indexterm zone="functions-schemavar">
-   <primary>Functions for access to schema variables</primary>
+   <primary>Schema Variable Functions</primary>
    <secondary>functions</secondary>
   </indexterm>
 
@@ -15760,10 +15760,12 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
 
   <para>
    These functions allow reading and writing schema variables values.
+   If the schema variable referenced does not exist (created using <xref linkend="sql-createvariable"/>)
+   these functions will (do something...).
   </para>
-
+<!-- I'm preferential to get_variable_value and set_variable_value -->
   <table id="functions-schemavar-tab">
-   <title>Functions for access to chema variables</title>
+   <title>Functions for access to schema variables</title>
    <tgroup cols="4">
     <thead>
      <row>
@@ -15773,14 +15775,13 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
       <entry>Description</entry>
      </row>
     </thead>
-
     <tbody>
      <row>
       <entry><literal><function>get_schema_variable(<parameter>variable</parameter>, <parameter>expected type</parameter>)</function></literal></entry>
       <entry><type>regclass</type>, <type>anyelement</type></entry>
       <entry><type>anyelement</type></entry>
       <entry>
-       Returns value of schema variables coverted to expected type.
+       Returns value of schema variable converted to expected type.
       </entry>
      </row>
 
@@ -15789,16 +15790,16 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
       <entry><type>regclass</type>, <type>anyelement</type></entry>
       <entry><type>void</type></entry>
       <entry>
-       Set a value of schema variable. Value is converted to type of schema variable.
+       Sets the value of schema variable to value, after converting the input to the correct type.
       </entry>
      </row>
 
     </tbody>
    </tgroup>
   </table>
-
+  An example:
   <para>
-   The usage is very simple:
+
 <programlisting>
 CREATE TEMP VARIABLE foo AS numeric;
 SELECT set_schema_variable('foo', 345.445);
diff --git a/doc/src/sgml/ref/create_variable.sgml b/doc/src/sgml/ref/create_variable.sgml
index 037fa087f5..c06b0e7517 100644
--- a/doc/src/sgml/ref/create_variable.sgml
+++ b/doc/src/sgml/ref/create_variable.sgml
@@ -16,7 +16,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>CREATE VARIABLE</refname>
-  <refpurpose>define a new schema secure typed variable</refpurpose>
+  <refpurpose>define a new permissioned typed schema variable</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -24,32 +24,39 @@ PostgreSQL documentation
 CREATE VARIABLE [ IF NOT EXISTS ] <replaceable class="parameter">name</replaceable> [ AS ] <replaceable class="parameter">data_type</replaceable> ]
 </synopsis>
  </refsynopsisdiv>
+<!-- a multiple variable version of this might be useful...
+     name data_type [, name data_type] -->
 
  <refsect1>
   <title>Description</title>
 
   <para>
    <command>CREATE VARIABLE</command> creates a new schema variable.
-   These variables are memory only non transactional, but typed and
-   secure. The access is controlled by rights defined by command
-   <command>GRANT</command> and command <command>REVOKE</command>.
+   These variables are scalar typed, non-transactional, and, like relations,
+   exist within a schema with access controlled via
+   <command>GRANT</command> and <command>REVOKE</command>.
   </para>
 
   <para>
-   The schema variable is initialized to NULL value. The content of
-   variable is lost when session is destroyed.
+   The value of a schema variable is session-local. Retrieving
+   a variable's value will return NULL unless its value has been set
+   to something else in the current session.
   </para>
 
   <para>
-   The schema variable can be any scalar only.
-   type.
+   Retrieval is done via the <function>get_schema_variable</function>dunxrion or the SQL
+   command <command>SELECT</command>.  Setting of values is done via the
+   <function>set_schema_variable</function> function or the SQL command
+   <command>LET</command>.
+   Notably, while schema variables are in many ways a kind of table you cannot use
+   <command>UPDATE</command> on them.
   </para>
 
   <para>
-   After a variable is created, you use the special functions
-   <function>get_schema_variables</function>, <function>set_schema_variables</function>.
-   type.
-  </para>
+   For purposes of name uniqueness relation-like objects (e.g., tables, indexes)
+   within the same schema are considered.  i.e., you cannot give a table and a
+   schema variable the same name.  This is a consequence of them being treated
+   like relations for purposes of <command>SELECT</command>.
  </refsect1>
 
  <refsect1>
@@ -60,10 +67,9 @@ CREATE VARIABLE [ IF NOT EXISTS ] <replaceable class="parameter">name</replaceab
     <term><literal>IF NOT EXISTS</literal></term>
     <listitem>
      <para>
-      Do not throw an error if a relation with the same name already exists.
-      A notice is issued in this case. Note that there is no guarantee that
-      the existing relation is anything like the variable that would have
-      been created - it might not even be a variable.
+      Do not throw an error if the name already exists. A notice is issued in this case.
+      Note that type of the variable is not considered, nor could it be since the namespace
+      searched contains non-variable objects.
      </para>
     </listitem>
    </varlistentry>
@@ -81,7 +87,7 @@ CREATE VARIABLE [ IF NOT EXISTS ] <replaceable class="parameter">name</replaceab
     <term><replaceable class="parameter">data_type</replaceable></term>
     <listitem>
      <para>
-      The name (optionally schema-qualified) of the data type ofvariable to be created.
+      The name (optionally schema-qualified) of the data type of the variable to be created.
      </para>
     </listitem>
    </varlistentry>
@@ -107,7 +113,7 @@ CREATE VARIABLE var1 AS integer;
   </para>
 
   <para>
-   Set a value of this variable:
+   Set this variable's value; then retrieve it converted to numeric.
 <programlisting>
 CREATE VARIABLE
 postgres=# select set_schema_variable('var1', 10);
@@ -129,7 +135,8 @@ postgres=# select get_schema_variable('var1', null::numeric);
   <title>Compatibility</title>
 
   <para>
-   <command>CREATE VARIABLE</command> is PostgreSQL feature
+   <command>CREATE VARIABLE</command> is a PostgreSQL feature.
+   <!-- The choice of wording here seems to be left to personal preference... -->
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/discard.sgml b/doc/src/sgml/ref/discard.sgml
index b348c02e0b..395453bba0 100644
--- a/doc/src/sgml/ref/discard.sgml
+++ b/doc/src/sgml/ref/discard.sgml
@@ -79,7 +79,8 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP | VARIABLES}
     <term><literal>VARIABLES</literal></term>
     <listitem>
      <para>
-      Releases content of all schema variables in current session.
+      Sets the value of all schema variables to NULL.
+      <!-- What happens to temporary schema variables -->
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/drop_variable.sgml b/doc/src/sgml/ref/drop_variable.sgml
index f6c2e46476..06130fd510 100644
--- a/doc/src/sgml/ref/drop_variable.sgml
+++ b/doc/src/sgml/ref/drop_variable.sgml
@@ -29,8 +29,9 @@ DROP VARIABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [,
   <title>Description</title>
 
   <para>
-   <command>DROP VARIABLE</command> removes schema variable.
+   <command>DROP VARIABLE</command> removes a schema variable.
    A variable can only be dropped by its owner or a superuser.
+   <!-- this would suggest that we need an alter variable owner to command -->
   </para>
  </refsect1>
 
@@ -75,6 +76,8 @@ DROP VARIABLE var1;
 
   <para>
    <command>DROP VARIABLE</command> is proprietary PostgreSQL command.
+   <!-- create variable is a "PostgreSQL feature",
+        this is a "proprietary PostgreSQL command" ... -->
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 7dde54ce0f..006364ebe5 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -173,6 +173,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    foreign servers,
    large objects,
    schemas,
+   schema variables,
    or tablespaces.
    For other types of objects, the default privileges
    granted to <literal>PUBLIC</literal> are as follows:
@@ -210,6 +211,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
        For sequences, this privilege also allows the use of the
        <function>currval</function> function.
        For large objects, this privilege allows the object to be read.
+       For schema variables, this privilege allows the <function>get_schema_variable</function>
+       to read the variable's value.
       </para>
      </listitem>
     </varlistentry>
@@ -245,6 +248,9 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
        <function>setval</function> functions.
        For large objects, this privilege allows writing or truncating the
        object.
+       For schema variables, this privilege allows <command>LET</command>
+       and <function>set_schema_variable</function> to modify the schema variable's
+       value.
       </para>
      </listitem>
     </varlistentry>
diff --git a/doc/src/sgml/ref/let.sgml b/doc/src/sgml/ref/let.sgml
index b040b5e1fe..e8bf3f6dd4 100644
--- a/doc/src/sgml/ref/let.sgml
+++ b/doc/src/sgml/ref/let.sgml
@@ -16,7 +16,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>LET</refname>
-  <refpurpose>change a schema variable</refpurpose>
+  <refpurpose>change a schema variable's value</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -29,7 +29,7 @@ LET <replaceable class="parameter">schema_variable</replaceable> = <replaceable
   <title>Description</title>
 
   <para>
-   The <command>LET</command> command sets specified schema variable.
+   The <command>LET</command> command updates the specified schema variable' value.
   </para>
 
  </refsect1>
@@ -42,7 +42,7 @@ LET <replaceable class="parameter">schema_variable</replaceable> = <replaceable
     <term><literal>schema_variable</literal></term>
     <listitem>
      <para>
-      Specifies that the name of schema variable.
+      The name of schema variable.
      </para>
     </listitem>
    </varlistentry>
@@ -51,7 +51,7 @@ LET <replaceable class="parameter">schema_variable</replaceable> = <replaceable
     <term><literal>sql expression</literal></term>
     <listitem>
      <para>
-      Any SQL expression.
+      An SQL expression, the result is cast to the schema variable's type.
      </para>
     </listitem>
    </varlistentry>
@@ -71,6 +71,8 @@ LET myvar = (SELECT sum(val) FROM tab);
   <title>Compatibility</title>
 
   <para>
+   <!-- this feels like it needs to be more specific,
+        but I don't know enough to make it so -->
    <literal>LET</literal> extends syntax defined in the SQL
    standard. The standard knows <literal>SET</literal> command,
    that is used for different purpouse in PostgreSQL.