diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index ca6b863793..c624fc2d9a 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3008,6 +3008,9 @@ ANALYZE measurement;
    <indexterm>
     <primary>foreign table</primary>
    </indexterm>
+   <indexterm>
+    <primary>user mapping</primary>
+   </indexterm>
 
    <para>
     <productname>PostgreSQL</productname> implements portions of the SQL/MED
@@ -3037,8 +3040,15 @@ ANALYZE measurement;
     tables</firstterm>, which define the structure of the remote data. A
     foreign table can be used in queries just like a normal table, but a
     foreign table has no storage in the PostgreSQL server.  Whenever it is
-    used, PostgreSQL asks the foreign data wrapper to fetch the data from the
-    external source.
+    used, <productname>PostgreSQL</productname> asks the foreign data wrapper
+    to fetch the data from the external source.
+   </para>
+
+   <para>
+    Accessing remote data may require authentication at the external
+    data source.  This information can be provided by a
+    <firstterm>user mapping</>, which can provide additional options based
+    on the current <productname>PostgreSQL</productname> role.
    </para>
 
    <para>
diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 9ab712f6d1..76ff243f5d 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -152,7 +152,9 @@ BeginForeignScan (ForeignScanState *node,
 </programlisting>
 
      Begin executing a foreign scan. This is called during executor startup.
-     It should perform any initialization needed before the scan can start.
+     It should perform any initialization needed before the scan can start,
+     but not start executing the actual scan (that should be done upon the
+     first call to <function>IterateForeignScan</>).
      The <structname>ForeignScanState</> node has already been created, but
      its <structfield>fdw_state</> field is still NULL.  Information about
      the table to scan is accessible through the