Subject: [PATCH v7 10/16] Improve sentences about the significance of the search path's first schema

From: "Karl O. Pinc" <[email-masked]>
Date: Sun, 24 Sep 2023 16:39:24 -0500

These two sentences have extra words, and can be improved with small
word re-ordering.  The word "again" could probably be removed as well
but it reads ok with it and it does not hurt to pound the point into
the reader's brain.

Note however that the original last sentence still isn't 100% correct,
because the default configuration includes "$user" at the start of the
search path.  So if an object is in the user's schema an unqualified
mention refers to something in the user's schema.  Hence, the
qualification that comes after the semicolon.  I thought about a
separate sentence, but the 2 parts are closely intertwined.  So,
semicolon.  It's all kind of a lot.  But, although I do believe in
removing extra content from sentences to make them shorter, more
clear, and memorable, I do think it's ok to repeat things when writing
narrative.  And the existing documentation is going for repetition so I
stuck with that.

Line break after each end of sentence to improve readability of future
patches.
---
 doc/src/sgml/ddl.sgml | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 075ff32991..ee30b7b575 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3106,12 +3106,14 @@ SHOW search_path;
    <para>
     The first schema in the search path that exists is the default
     location for creating new objects.  That is the reason that by
-    default objects are created in the public schema.  When objects
-    are referenced in any other context without schema qualification
-    (table modification, data modification, or query commands) the
-    search path is traversed until a matching object is found.
-    Therefore, in the default configuration, any unqualified access
-    again can only refer to the public schema.
+    default objects are created in the public schema.
+    When objects are referenced in a context without schema qualification
+    (table modification, data modification, or query commands) the search path
+    is traversed until a matching object is found.
+    Therefore, again, in the default configuration, any unqualified name
+    refers to an object in the public schema; unless, given the default search
+    path, there is an object with that name accessible in the schema having
+    the name of the current user.
    </para>
 
    <para>
-- 
2.30.2

--MP_/VSGM3xNEmY7iJyL2wuWRCjV
Content-Type: text/x-patch
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename=v7-0011-Add-a-sub-section-to-describe-schema-resolution.patch