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í"
>From 909355851bfb21086422e6edc0b2b75fbaa58418 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvhe...@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

Reply via email to