Re: doc: create table improvements

On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter@eisentraut.org> wrote:
> >  > +   The reliability characteristics of a table are governed by its
> >  > +   persistence mode.  The default mode is described
> >  > +   <link linkend="wal-reliability">here</link>
> >  > +   There are two alternative modes that can be specified during
> >  > +   table creation:
> >  > +   <link linkend="sql-createtable-temporary">temporary</link> and
> >  > +   <link linkend="sql-createtable-unlogged">unlogged</link>.
> >
> > Not sure reliability is the best word here.  I mean, a temporary table
> > isn't any less reliable than any other table.  It just does different
> > things.
>
> Given the name of the section where this is all discussed I'm having trouble
> going with a different word. 

This patch has rotted somewhat, and parts of it have become obsolete
with commit e2bab2d792.  Still, I think that it is a good idea to shorten
the lines in the synopsis.

A detailed review:

> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
> index 02f31d2d6f..9a5dafb9af 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> [...]
> +<phrase>and <replaceable>column_storage</replaceable> is:</phrase>
> +
> +STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } [ COMPRESSION <replaceable>compression_method</replaceable>
]
> [...]

I don't know if "column_storage" is descriptive.  After all, this is solely
about TOAST details, which is only one aspect of storage.
I have renamed it to "oversize_storage".


@@ -118,11 +127,21 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
   <title>Description</title>

   <para>
-   <command>CREATE TABLE</command> will create a new, initially empty table
+   <command>CREATE TABLE</command> will create a new, initially empty, table
    in the current database. The table will be owned by the user issuing the
    command.
   </para>

I am not a native speaker, but the sentence feels better to me without
the extra comma.  I took the liberty to undo this change, partly because
it is unrelated to the topic of the patch.

+  <para>
+   The reliability characteristics of a table are governed by its
+   persistence mode.  The default mode is described
+   <link linkend="wal-reliability">here</link>
+   There are two alternative modes that can be specified during
+   table creation:
+   <link linkend="sql-createtable-temporary">temporary</link> and
+   <link linkend="sql-createtable-unlogged">unlogged</link>.
+  </para>

I agree with Peter that "reliability" is not ideal.  I went with
"durability" instead.  I removed the link to the reliability discussion
and rephrased the sentence somewhat.

+
+     <para>
+      If specified on a partitioned table the property is recorded but ignored:
+      the entire partitioned table is not automatically truncated after a crash
+      or unclean shutdown.
+     </para>

This has become obsolete with e2bab2d792, so I removed it.

Attached is an updated patch.

Yours,
Laurenz Albe