Date: Sat, 29 Jan 2022 18:18:50 -0600
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	Kyotaro Horiguchi <horikyota.ntt@gmail.com>,
	pgsql-hackers@lists.postgresql.org, bruce@momjian.us,
	tgl@sss.pgh.pa.us
Subject: Re: GUC flags
Message-ID: <20220130001849.GR23027@telsasoft.com>
References: <YdZ7zCymonPV4//X@paquier.xyz>
 <20220106053641.GW14051@telsasoft.com>
 <20220125010729.GC23027@telsasoft.com>
 <d363c358-2c67-92bc-660f-ff82636c155f@enterprisedb.com>
 <20220125180751.GH23027@telsasoft.com>
 <YfCb03sRzkgNVwbL@paquier.xyz>
 <20220126034426.GN23027@telsasoft.com>
 <YfDqSVZlzdzZO9x6@paquier.xyz>
 <20220128043621.GA23027@telsasoft.com>
 <YfTg/WHNLVVygy8v@paquier.xyz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YfTg/WHNLVVygy8v@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Archived-At: 
 <https://www.postgresql.org/message-id/20220130001849.GR23027%40telsasoft.com>
Precedence: bulk

On Sat, Jan 29, 2022 at 03:38:53PM +0900, Michael Paquier wrote:
> +-- Three exceptions as of transaction_*
> +SELECT name FROM pg_settings_flags
> +  WHERE NOT no_show_all AND no_reset_all
> +  ORDER BY 1;
> +          name          
> +------------------------
> + transaction_deferrable
> + transaction_isolation
> + transaction_read_only
> +(3 rows)

I think "as of" is not the right phrase here.
Maybe say: Exceptions are transaction_*

> --- a/doc/src/sgml/func.sgml
> +++ b/doc/src/sgml/func.sgml
> @@ -23596,6 +23596,45 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
> +       <para>
> +        Returns an array of the flags associated with the given GUC, or
> +        <literal>NULL</literal> if the  does not exist.  The result is

I guess it should say "if the GUC does not exist".

> +        an empty array if the GUC exists but there are no flags to show,
> +        as supported by the list below.

I'd say "...but none of the GUC's flags are exposed by this function."

> +        The following flags are exposed (the most meaningful ones are
> +        included):

"The most meaningful ones are included" doesn't seem to add anything.
Maybe it'd be useful to say "(Only the most useful flags are exposed)"

> +          <literal>EXPLAIN</literal>, parameters included in
> +          <command>EXPLAIN</command> commands.
> +         </member>
> +         <member>

I think the description is wrong, or just copied from the others.
EXPLAIN is for GUCs which are shown in EXPLAIN(SETTINGS).

|EXPLAIN, parameters included in EXPLAIN commands.
|NO_SHOW_ALL, parameters excluded from SHOW ALL commands.
|NO_RESET_ALL, parameters excluded from RESET ALL commands.
|NOT_IN_SAMPLE, parameters not included in postgresql.conf by default.
|RUNTIME_COMPUTED, runtime-computed parameters. 

Instead of a comma, these should use a colon, or something else?

-- 
Justin