Feedback-ID: ia2694551:Fastmail
Date: Tue, 7 Nov 2023 10:33:03 +0100
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Nathan Bossart <nathandbossart@gmail.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>, 
	Peter Eisentraut <peter@eisentraut.org>, Tom Lane <tgl@sss.pgh.pa.us>, 
	Daniel Gustafsson <daniel@yesql.se>, Peter Smith <smithpb2250@gmail.com>, 
	PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: GUC names in messages
Message-ID: <202311070933.ngoeikm2v4k4@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="sgov2mlwyhxqc24m"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20231102015239.GA82553@nathanxps13>
Archived-At: <https://www.postgresql.org/message-id/202311070933.ngoeikm2v4k4%40alvherre.pgsql>
Precedence: bulk


--sgov2mlwyhxqc24m
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On 2023-Nov-01, Nathan Bossart wrote:

> On Wed, Nov 01, 2023 at 09:46:52PM +0100, Laurenz Albe wrote:
> > I agree for names with underscores in them.  But I think that quoting
> > is necessary for names like "timezone" or "datestyle" that might be
> > mistaken for normal words.  My personal preference is to always quote
> > GUC names, but I think it is OK not to quote GOCs whose name are
> > clearly not natural language words.
> 
> +1, IMHO quoting GUC names makes it abundantly clear that they are special
> identifiers.  In de4d456, we quoted the role names in a bunch of messages.
> We didn't quote the attribute/option names, but those are in all-caps, so
> they already stand out nicely.

I like this, and I propose we codify it in the message style guide.  How
about this?  We can start looking at code changes to make once we decide
we agree with this.

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"La verdad no siempre es bonita, pero el hambre de ella sí"

--sgov2mlwyhxqc24m
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: attachment;
	filename="0001-Message-style-Add-paragraph-about-quoting-names.patch"

From 909355851bfb21086422e6edc0b2b75fbaa58418 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Tue, 7 Nov 2023 10:24:00 +0100
Subject: [PATCH] Message style: Add paragraph about quoting names

---
 doc/src/sgml/sources.sgml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 06d995e4b7..d72e114ea3 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -532,23 +532,31 @@ Hint:       The addendum, written as a complete sentence.
   <simplesect id="error-style-guide-quotes">
    <title>Use of Quotes</title>
 
    <para>
     Always use quotes to delimit file names, user-supplied identifiers, and
     other variables that might contain words.  Do not use them to mark up
     variables that will not contain words (for example, operator names).
    </para>
 
    <para>
     There are functions in the backend that will double-quote their own output
     as needed (for example, <function>format_type_be()</function>).  Do not put
     additional quotes around the output of such functions.
    </para>
 
+   <para>
+    In messages containing configuration variable names, quotes are
+    not necessary when the names are visibly not English natural words, such
+    as when they have underscores or are all-uppercase.  Otherwise, quotes
+    must be added.  Do include double-quotes in a message where an arbitrary
+    variable name is to be expanded.
+   </para>
+
    <para>
     Rationale: Objects can have names that create ambiguity when embedded in a
     message.  Be consistent about denoting where a plugged-in name starts and
     ends.  But don't clutter messages with unnecessary or duplicate quote
     marks.
    </para>
 
   </simplesect>
-- 
2.39.2


--sgov2mlwyhxqc24m--