Restructure foreign data wrapper chapter so it has more than one section.

As noted by Laurenz Albe, our SGML tools deal rather oddly with chapters
having just one .  Perhaps the tooling could be fixed, but really
the design of this chapter's introduction is pretty bogus anyhow.  Split
it into a true introduction and a  about the FDW functions, so
that it reads better and dodges the lack-of-a-chapter-TOC problem.

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 0637de7d1f625b6f74a71884f15b8894c3a01eaf..9ab712f6d18e1e6de26cd64883669c6370f1721c 100644 (file)
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -17,43 +17,6 @@
     to write a new foreign data wrapper.
    
 
-   
-    The FDW author needs to implement a handler function, and optionally
-    a validator function. Both functions must be written in a compiled
-    language such as C, using the version-1 interface.
-    For details on C language calling conventions and dynamic loading,
-    see .
-   
-
-   
-    The handler function simply returns a struct of function pointers to
-    callback functions that will be called by the planner and executor.
-    Most of the effort in writing an FDW is in implementing these callback
-    functions.
-    The handler function must be registered with
-    PostgreSQL as taking no arguments and returning
-    the special pseudo-type fdw_handler.
-    The callback functions are plain C functions and are not visible or
-    callable at the SQL level.
-   
-
-   
-    The validator function is responsible for validating options given in
-    CREATE and ALTER commands for its
-    foreign data wrapper, as well as foreign servers, user mappings, and
-    foreign tables using the wrapper.
-    The validator function must be registered as taking two arguments, a text
-    array containing the options to be validated, and an OID representing the
-    type of object the options are associated with (in the form of the OID
-    of the system catalog the object would be stored in, either
-    ForeignDataWrapperRelationId,
-    ForeignServerRelationId,
-    UserMappingRelationId,
-    or ForeignTableRelationId).
-    If no validator function is supplied, options are not checked at object
-    creation time or object alteration time.
-   
-
    
     The foreign data wrappers included in the standard distribution are good
     references when trying to write your own.  Look into the
@@ -71,7 +34,51 @@
     
    
 
-   
+   
+    Foreign Data Wrapper Functions
+
+    
+     The FDW author needs to implement a handler function, and optionally
+     a validator function. Both functions must be written in a compiled
+     language such as C, using the version-1 interface.
+     For details on C language calling conventions and dynamic loading,
+     see .
+    
+
+    
+     The handler function simply returns a struct of function pointers to
+     callback functions that will be called by the planner and executor.
+     Most of the effort in writing an FDW is in implementing these callback
+     functions.
+     The handler function must be registered with
+     PostgreSQL as taking no arguments and
+     returning the special pseudo-type fdw_handler.  The
+     callback functions are plain C functions and are not visible or
+     callable at the SQL level.  The callback functions are described in
+     .
+    
+
+    
+     The validator function is responsible for validating options given in
+     CREATE and ALTER commands for its
+     foreign data wrapper, as well as foreign servers, user mappings, and
+     foreign tables using the wrapper.
+     The validator function must be registered as taking two arguments, a
+     text array containing the options to be validated, and an OID
+     representing the type of object the options are associated with (in
+     the form of the OID of the system catalog the object would be stored
+     in, either
+     ForeignDataWrapperRelationId,
+     ForeignServerRelationId,
+     UserMappingRelationId,
+     or ForeignTableRelationId).
+     If no validator function is supplied, options are not checked at object
+     creation time or object alteration time.
+    
+
+   
+
+   
     Foreign Data Wrapper Callback Routines