Do some copy-editing on the docs for row-level security.

Clarifications, markup improvements, corrections of misleading or
outright wrong statements.

doc/src/sgml/ref/alter_policy.sgml

@@ -16,13 +16,14 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>ALTER POLICY</refname>
-  <refpurpose>change the definition of a policy</refpurpose>
+  <refpurpose>change the definition of a row level security policy</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
 <synopsis>
+ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
+
 ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
-    [ RENAME TO <replaceable class="PARAMETER">new_name</replaceable> ]
     [ TO { <replaceable class="parameter">role_name</replaceable> | PUBLIC | CURRENT_USER | SESSION_USER } [, ...] ]
     [ USING ( <replaceable class="parameter">using_expression</replaceable> ) ]
     [ WITH CHECK ( <replaceable class="parameter">check_expression</replaceable> ) ]
@@ -33,14 +34,22 @@ ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable c
   <title>Description</title>
 
   <para>
-   <command>ALTER POLICY</command> changes the <replaceable class="parameter">
-   definition</replaceable> of an existing policy.
+   <command>ALTER POLICY</command> changes the definition of an existing
+   row-level security policy.
   </para>
 
   <para>
    To use <command>ALTER POLICY</command>, you must own the table that
    the policy applies to.
   </para>
+
+  <para>
+   In the second form of <command>ALTER POLICY</command>, the role list,
+   <replaceable class="parameter">using_expression</replaceable>, and
+   <replaceable class="parameter">check_expression</replaceable> are replaced
+   independently if specified.  When one of those clauses is omitted, the
+   corresponding part of the policy is unchanged.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -79,9 +88,9 @@ ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable c
     <term><replaceable class="parameter">role_name</replaceable></term>
     <listitem>
      <para>
-      The role to which the policy applies.  Multiple roles can be specified at one time.
-      To apply the policy to all roles, use <literal>PUBLIC</literal>, which is also
-      the default.
+      The role(s) to which the policy applies.  Multiple roles can be
+      specified at one time.  To apply the policy to all roles,
+      use <literal>PUBLIC</literal>.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_policy.sgml

@@ -16,7 +16,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>DROP POLICY</refname>
-  <refpurpose>remove a policy from a table</refpurpose>
+  <refpurpose>remove a row level security policy from a table</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -32,10 +32,9 @@ DROP POLICY [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ON <
    <command>DROP POLICY</command> removes the specified policy from the table.
    Note that if the last policy is removed for a table and the table still has
    row level security enabled via <command>ALTER TABLE</command>, then the
-   default-deny policy will be used.  <command>ALTER TABLE</command> can be used
-   to disable row level security for a table using
-   <literal>DISABLE ROW SECURITY</literal>, whether policies for the table
-   exist or not.
+   default-deny policy will be used.  <literal>ALTER TABLE ... DISABLE ROW
+   LEVEL SECURITY</literal> can be used to disable row level security for a
+   table, whether policies for the table exist or not.
   </para>
  </refsect1>