doc: Move enum storage commentary to top of section
Per suggestion over on -docs:
/messages/by-id/BL0PR06MB4978F6C0B69F3F03AEBED0FBB3C29@BL0PR06MB4978.namprd06.prod.outlook.com
David J.
Attachments:
0001-doc-Move-enum-storage-size-to-top-of-section.patchapplication/octet-stream; name=0001-doc-Move-enum-storage-size-to-top-of-section.patchDownload
From 1657be6863c8d743977d187169603da9e816a471 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Thu, 9 Jun 2022 16:04:44 +0000
Subject: [PATCH] doc: Move enum storage size to top of section
This is done to conform to the location used by other
data types.
Suggestion by Sumit Sengupta
Discussion: https://www.postgresql.org/message-id/BL0PR06MB4978F6C0B69F3F03AEBED0FBB3C29@BL0PR06MB4978.namprd06.prod.outlook.com
---
doc/src/sgml/datatype.sgml | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 8e30b82273..77e75f09e2 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -3155,6 +3155,13 @@ SELECT * FROM test1 WHERE a;
a piece of data.
</para>
+ <para>
+ An enum value occupies four bytes on disk. The length of an enum
+ value's textual label is limited by the <symbol>NAMEDATALEN</symbol>
+ setting compiled into <productname>PostgreSQL</productname>; in standard
+ builds this means at most 63 bytes.
+ </para>
+
<sect2>
<title>Declaration of Enumerated Types</title>
@@ -3279,13 +3286,6 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
values be changed, short of dropping and re-creating the enum type.
</para>
- <para>
- An enum value occupies four bytes on disk. The length of an enum
- value's textual label is limited by the <symbol>NAMEDATALEN</symbol>
- setting compiled into <productname>PostgreSQL</productname>; in standard
- builds this means at most 63 bytes.
- </para>
-
<para>
The translations from internal enum values to textual labels are
kept in the system catalog
--
2.25.1
On Thu, 9 Jun 2022 at 18:12, David G. Johnston
<david.g.johnston@gmail.com> wrote:
Per suggestion over on -docs:
/messages/by-id/BL0PR06MB4978F6C0B69F3F03AEBED0FBB3C29@BL0PR06MB4978.namprd06.prod.outlook.com
I agree with moving the size of an enum into the top, but I don't
think that the label length documentation also should be included in
the top section. It seems excessively detailed for that section with
its reference to NAMEDATALEN.
-Matthias
On Wed, Jul 6, 2022 at 10:24 AM Matthias van de Meent <
boekewurm+postgres@gmail.com> wrote:
On Thu, 9 Jun 2022 at 18:12, David G. Johnston
<david.g.johnston@gmail.com> wrote:Per suggestion over on -docs:
/messages/by-id/BL0PR06MB4978F6C0B69F3F03AEBED0FBB3C29@BL0PR06MB4978.namprd06.prod.outlook.com
I agree with moving the size of an enum into the top, but I don't
think that the label length documentation also should be included in
the top section. It seems excessively detailed for that section with
its reference to NAMEDATALEN.-Matthias
Agreed.
Tangentially: It does seem a bit unusual to call the fact that the values
both case-sensitive and limited to the length of a system identifier an
implementation detail. But if anything the length is more of one than the
case-sensitivity. Specifying NAMEDATALEN here seems like it breaks
encapsulation, it could refer by comparison to an identifier and only those
that care can learn how that length might be changed in a custom build of
PostgreSQL.
David J.
On Wed, Jul 6, 2022 at 10:34:58AM -0700, David G. Johnston wrote:
Agreed.
Tangentially: It does seem a bit unusual to call the fact that the values both
case-sensitive and limited to the length of a system identifier an
implementation detail. But if anything the length is more of one than the
case-sensitivity. Specifying NAMEDATALEN here seems like it breaks
encapsulation, it could refer by comparison to an identifier and only those
that care can learn how that length might be changed in a custom build of
PostgreSQL.
I don't think we can do much to improve what we have already in the
docs.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
On Fri, Jul 8, 2022 at 09:21:31PM -0400, Bruce Momjian wrote:
On Wed, Jul 6, 2022 at 10:34:58AM -0700, David G. Johnston wrote:
Agreed.
Tangentially: It does seem a bit unusual to call the fact that the values both
case-sensitive and limited to the length of a system identifier an
implementation detail. But if anything the length is more of one than the
case-sensitivity. Specifying NAMEDATALEN here seems like it breaks
encapsulation, it could refer by comparison to an identifier and only those
that care can learn how that length might be changed in a custom build of
PostgreSQL.I don't think we can do much to improve what we have already in the
docs.
I have marked the commit-fest entry as returned with feedback.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson