Improve the documentation of the 'join_collapse_limit' GUC var. Thanks to

Tom Lane for some editorial suggestions.

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 61d7ca89674e1118387bf8330a987e3c3ce1daf6..a38e6c01598b1d776ecca922d31b90cec31d0749 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 
 
 
@@ -1462,11 +1462,11 @@ SET ENABLE_SEQSCAN TO OFF;
       from_collapse_limit (integer)
       
        
-        The planner will merge sub-queries into upper queries if the resulting
-        FROM list would have no more than this many items.  Smaller values
-        reduce planning time but may yield inferior query plans.
-        The default is 8.  It is usually wise to keep this less than
-        geqo_threshold.
+        The planner will merge sub-queries into upper queries if the
+        resulting FROM list would have no more than
+        this many items.  Smaller values reduce planning time but may
+        yield inferior query plans.  The default is 8.  It is usually
+        wise to keep this less than geqo_threshold.
        
       
      
@@ -1475,14 +1475,48 @@ SET ENABLE_SEQSCAN TO OFF;
       join_collapse_limit (integer)
       
        
-        The planner will flatten explicit inner JOIN constructs
-        into lists of FROM items whenever a list of no more than
-        this many items would result.  Usually this is set the same as
-        from_collapse_limit.  Setting it to 1 prevents any
-        flattening of inner JOINs, allowing explicit
-        JOIN syntax to be used to control the join order.
-        Intermediate values might be useful to trade off planning time
-        against quality of plan.
+        The planner will rewrite explicit inner JOIN
+        constructs into lists of FROM items whenever a
+        list of no more than this many items in total would
+        result. Prior to PostgreSQL 7.4, joins
+        specified via the JOIN construct would
+        never be reordered by the query planner. The query planner has
+        subsequently been improved so that inner joins written in this
+        form can be reordered; this configuration variable controls
+        the extent to which this reordering is performed.
+        
+         
+          At present, the order of outer joins specified via the
+          JOIN construct is never adjusted by the query
+          planner; therefore, join_collapse_limit has no
+          effect on this behavior. The planner may be improved to
+          reorder some classes of outer joins in a future release of
+          PostgreSQL.
+         
+        
+       
+
+       
+        By default, this variable is set to
+        from_collapse_limit, which is appropriate
+        for most uses. Setting it to 1 prevents any reordering of
+        inner JOINs. Thus, the explicit join order
+        specified in the query will be the actual order in which the
+        relations are joined. The query planner does not always choose
+        the optimal join order; advanced users may elect to
+        temporarily set this variable to 1, and then specify the join
+        order they desire explicitly. Another consequence of setting
+        this variable to 1 is that the query planner will behave more
+        like the PostgreSQL 7.3 query
+        planner, which some users might find useful for backward
+        compatibility reasons.
+       
+
+       
+        Setting this variable to a value between 1 and
+        from_collapse_limit might be useful to
+        trade off planning time against the quality of the chosen plan
+        (higher values produce better plans).
        
       
      
@@ -2583,9 +2617,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       max_identifier_length (integer)
       
        
-        Shows the maximum identifier length. It is determined as one less than
-        the value of NAMEDATALEN when building the server. The
-        default value of NAMEDATALEN is 64; therefore the default
+        Shows the maximum identifier length. It is determined as one
+        less than the value of NAMEDATALEN when building
+        the server. The default value of NAMEDATALEN is
+        64; therefore the default
         max_identifier_length is 63.