Should enum GUCs be listed as such in config.sgml?

Started by Tom Laneover 17 years ago9 messages

tgl@sss.pgh.pa.us

over 17 years ago

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

regards, tom lane

Magnus Hagander

magnus@hagander.net

over 17 years ago

In reply to: Tom Lane (#1)

Re: Should enum GUCs be listed as such in config.sgml?

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

From the perspective of the person setting it in the config, it still
"looks like a string", which is why I chose not to change it. I think
it'd make things more confusing.

18.1 probably deserves a note about it though, I'll see if I can come up
with something good there.

//Magnus

bruce@momjian.us

over 17 years ago

In reply to: Tom Lane (#1)

Re: Should enum GUCs be listed as such in config.sgml?

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

I looked into this and I think the documentation is fine. If enums
didn't require quotes but strings did, we would document them
differently, but the fact is that enums are the same as strings except
enums have a limited number of possible values --- that isn't something
that is usually identified in a variable type definition heading.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

bruce@momjian.us

over 17 years ago

In reply to: Bruce Momjian (#3)

Re: Should enum GUCs be listed as such in config.sgml?

bruce wrote:

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

I looked into this and I think the documentation is fine. If enums
didn't require quotes but strings did, we would document them
differently, but the fact is that enums are the same as strings except
enums have a limited number of possible values --- that isn't something
that is usually identified in a variable type definition heading.

Looking further, it seems we still have an inconsistency problem because
pg_settings mentions enum; should we just change that to 'string'?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Import Notes

Reply to msg id not found:  | Resolved by subject fallback

tgl@sss.pgh.pa.us

over 17 years ago

In reply to: Bruce Momjian (#4)

Re: Should enum GUCs be listed as such in config.sgml?

Bruce Momjian <bruce@momjian.us> writes:

bruce wrote:

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

I looked into this and I think the documentation is fine. If enums
didn't require quotes but strings did, we would document them
differently, but the fact is that enums are the same as strings except
enums have a limited number of possible values --- that isn't something
that is usually identified in a variable type definition heading.

By that logic, we should not distinguish integers and floats. One's
just a restricted form of the other.

Looking further, it seems we still have an inconsistency problem because
pg_settings mentions enum; should we just change that to 'string'?

No, and in fact pg_settings is the counterexample to your conclusion
that it's okay to pretend enums are the same as strings: since it has an
enumvals column that's populated for enums and not for strings, there
is clearly a genuine user-visible difference.

Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...

regards, tom lane

Magnus Hagander

magnus@hagander.net

over 17 years ago

In reply to: Tom Lane (#5)

Re: Should enum GUCs be listed as such in config.sgml?

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

bruce wrote:

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

I looked into this and I think the documentation is fine. If enums
didn't require quotes but strings did, we would document them
differently, but the fact is that enums are the same as strings except
enums have a limited number of possible values --- that isn't something
that is usually identified in a variable type definition heading.

By that logic, we should not distinguish integers and floats. One's
just a restricted form of the other.

Looking further, it seems we still have an inconsistency problem because
pg_settings mentions enum; should we just change that to 'string'?

No, and in fact pg_settings is the counterexample to your conclusion
that it's okay to pretend enums are the same as strings: since it has an
enumvals column that's populated for enums and not for strings, there
is clearly a genuine user-visible difference.

Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...

Yes, it's on my TODO list waiting to bubble up to the top. Not forgotten
(yet).

//Magnus

Magnus Hagander

magnus@hagander.net

about 17 years ago

In reply to: Tom Lane (#5)

1 attachment(s)

Re: Should enum GUCs be listed as such in config.sgml?

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

bruce wrote:

Tom Lane wrote:

Currently, config.sgml still describes the new "enum" GUC variables
as being of type "string" --- but pg_settings says they are "enum".
This is not very consistent, but I wonder whether changing the docs
would be more confusing or less so. I note that section 18.1 doesn't
mention the enum alternative either.

I looked into this and I think the documentation is fine. If enums
didn't require quotes but strings did, we would document them
differently, but the fact is that enums are the same as strings except
enums have a limited number of possible values --- that isn't something
that is usually identified in a variable type definition heading.

By that logic, we should not distinguish integers and floats. One's
just a restricted form of the other.

Looking further, it seems we still have an inconsistency problem because
pg_settings mentions enum; should we just change that to 'string'?

No, and in fact pg_settings is the counterexample to your conclusion
that it's okay to pretend enums are the same as strings: since it has an
enumvals column that's populated for enums and not for strings, there
is clearly a genuine user-visible difference.

Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...

Meh, I seem to have forgotten this one again. Here's a suggestion, seems
ok, or were you thinking about something more?

//Magnus

Attachments:

gucdocs.difftext/x-diff; name=gucdocs.diffDownload

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index b0de16e..1cfa8bc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -20,8 +20,8 @@
 
    <para>
     All parameter names are case-insensitive. Every parameter takes a
-    value of one of four types: Boolean, integer, floating point,
-    or string. Boolean values can be written as <literal>ON</literal>,
+    value of one of five types: Boolean, integer, floating point,
+    string or enum. Boolean values can be written as <literal>ON</literal>,
     <literal>OFF</literal>, <literal>TRUE</literal>,
     <literal>FALSE</literal>, <literal>YES</literal>,
     <literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
@@ -43,6 +43,12 @@
    </para>
 
    <para>
+    Enum settings are specified the same way as string settings, but they
+    are limited in which strings are accepted. For each setting the available
+    are listed in <literal>pg_settings.enumvals</>.
+   </para>
+
+   <para>
     One way to set these parameters is to edit the file
     <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
     which is normally kept in the data directory. (<application>initdb</>
@@ -1329,7 +1335,7 @@ SET ENABLE_SEQSCAN TO OFF;
      </varlistentry>
      
      <varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method">
-      <term><varname>wal_sync_method</varname> (<type>string</type>)</term>
+      <term><varname>wal_sync_method</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>wal_sync_method</> configuration parameter</primary>
       </indexterm>
@@ -2464,7 +2470,7 @@ local0.*    /var/log/postgresql
      </varlistentry>
 
      <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
-      <term><varname>syslog_facility</varname> (<type>string</type>)</term>
+      <term><varname>syslog_facility</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>syslog_facility</> configuration parameter</primary>
       </indexterm>
@@ -2511,7 +2517,7 @@ local0.*    /var/log/postgresql
      <variablelist>
 
      <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
-      <term><varname>client_min_messages</varname> (<type>string</type>)</term>
+      <term><varname>client_min_messages</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>client_min_messages</> configuration parameter</primary>
       </indexterm>
@@ -2532,7 +2538,7 @@ local0.*    /var/log/postgresql
      </varlistentry>
 
      <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
-      <term><varname>log_min_messages</varname> (<type>string</type>)</term>
+      <term><varname>log_min_messages</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_min_messages</> configuration parameter</primary>
       </indexterm>
@@ -2554,7 +2560,7 @@ local0.*    /var/log/postgresql
      </varlistentry>
 
      <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
-      <term><varname>log_error_verbosity</varname> (<type>string</type>)</term>
+      <term><varname>log_error_verbosity</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_error_verbosity</> configuration parameter</primary>
       </indexterm>
@@ -2570,7 +2576,7 @@ local0.*    /var/log/postgresql
      </varlistentry>
 
      <varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement">
-      <term><varname>log_min_error_statement</varname> (<type>string</type>)</term>
+      <term><varname>log_min_error_statement</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_min_error_statement</> configuration parameter</primary>
       </indexterm>
@@ -3056,7 +3062,7 @@ local0.*    /var/log/postgresql
      </varlistentry>
 
      <varlistentry id="guc-log-statement" xreflabel="log_statement">
-      <term><varname>log_statement</varname> (<type>string</type>)</term>
+      <term><varname>log_statement</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_statement</> configuration parameter</primary>
       </indexterm>
@@ -3314,7 +3320,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>
 
      <varlistentry id="guc-track-functions" xreflabel="track_functions">
-      <term><varname>track_functions</varname> (<type>string</type>)</term>
+      <term><varname>track_functions</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>track_functions</> configuration parameter</primary>
       </indexterm>
@@ -3828,7 +3834,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       <indexterm>
        <primary><varname>default_transaction_isolation</> configuration parameter</primary>
       </indexterm>
-      <term><varname>default_transaction_isolation</varname> (<type>string</type>)</term>
+      <term><varname>default_transaction_isolation</varname> (<type>enum</type>)</term>
       <listitem>
        <para>
         Each SQL transaction has an isolation level, which can be
@@ -3871,7 +3877,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>
 
      <varlistentry id="guc-session-replication-role" xreflabel="session_replication_role">
-      <term><varname>session_replication_role</varname> (<type>string</type>)</term>
+      <term><varname>session_replication_role</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>session_replication_role</> configuration parameter</primary>
       </indexterm>
@@ -3933,7 +3939,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>
 
      <varlistentry id="guc-xmlbinary" xreflabel="xmlbinary">
-      <term><varname>xmlbinary</varname> (<type>string</type>)</term>
+      <term><varname>xmlbinary</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>xmlbinary</> configuration parameter</primary>
       </indexterm>
@@ -3960,7 +3966,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>
 
      <varlistentry id="guc-xmloption" xreflabel="xmloption">
-      <term><varname>xmloption</varname> (<type>string</type>)</term>
+      <term><varname>xmloption</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>xmloption</> configuration parameter</primary>
       </indexterm>
@@ -4026,7 +4032,7 @@ SET XML OPTION { DOCUMENT | CONTENT };
      </varlistentry>
 
      <varlistentry id="guc-intervalstyle" xreflabel="IntervalStyle">
-      <term><varname>IntervalStyle</varname> (<type>string</type>)</term>
+      <term><varname>IntervalStyle</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>IntervalStyle</> configuration parameter</primary>
       </indexterm>
@@ -4514,7 +4520,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      </varlistentry>
 
      <varlistentry id="guc-backslash-quote" xreflabel="backslash_quote">
-      <term><varname>backslash_quote</varname> (<type>string</type>)</term>
+      <term><varname>backslash_quote</varname> (<type>enum</type>)</term>
       <indexterm><primary>strings</><secondary>backslash quotes</></>
       <indexterm>
        <primary><varname>backslash_quote</> configuration parameter</primary>
@@ -4602,7 +4608,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      </varlistentry>
 
      <varlistentry id="guc-regex-flavor" xreflabel="regex_flavor">
-      <term><varname>regex_flavor</varname> (<type>string</type>)</term>
+      <term><varname>regex_flavor</varname> (<type>enum</type>)</term>
       <indexterm><primary>regular expressions</></>
       <indexterm>
        <primary><varname>regex_flavor</> configuration parameter</primary>

tgl@sss.pgh.pa.us

about 17 years ago

In reply to: Magnus Hagander (#7)

Re: Should enum GUCs be listed as such in config.sgml?

Magnus Hagander <magnus@hagander.net> writes:

Tom Lane wrote:

Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...

Meh, I seem to have forgotten this one again. Here's a suggestion, seems
ok, or were you thinking about something more?

Needs a bit of proofreading but this is more or less what I had in
mind.

+    Enum settings are specified the same way as string settings, but they
+    are limited in which strings are accepted. For each setting the available
+    are listed in <literal>pg_settings.enumvals</>.

IIRC the comparisons are case-insensitive; if so the fact should be
mentioned here.

regards, tom lane

Magnus Hagander

magnus@hagander.net

about 17 years ago

In reply to: Tom Lane (#8)

Re: Should enum GUCs be listed as such in config.sgml?

Tom Lane wrote:

Magnus Hagander <magnus@hagander.net> writes:

Tom Lane wrote:

Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...

Meh, I seem to have forgotten this one again. Here's a suggestion, seems
ok, or were you thinking about something more?

Needs a bit of proofreading but this is more or less what I had in
mind.
+    Enum settings are specified the same way as string settings, but they
+    are limited in which strings are accepted. For each setting the available
+    are listed in <literal>pg_settings.enumvals</>.
IIRC the comparisons are case-insensitive; if so the fact should be
mentioned here.

Updated, added, and applied.

//Magnus