public inbox for [email protected]
help / color / mirror / Atom feedFrom: Alvaro Herrera <[email protected]>
To: Nathan Bossart <[email protected]>
Cc: Laurenz Albe <[email protected]>
Cc: Peter Eisentraut <[email protected]>
Cc: Tom Lane <[email protected]>
Cc: Daniel Gustafsson <[email protected]>
Cc: Peter Smith <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Subject: Re: GUC names in messages
Date: Tue, 7 Nov 2023 10:33:03 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <20231102015239.GA82553@nathanxps13>
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í"
Attachments:
[text/x-diff] 0001-Message-style-Add-paragraph-about-quoting-names.patch (1.7K, ../[email protected]/2-0001-Message-style-Add-paragraph-about-quoting-names.patch)
download | inline diff:
From 909355851bfb21086422e6edc0b2b75fbaa58418 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <[email protected]>
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
view thread (5+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: GUC names in messages
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox