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  wrote:
> >  > +   The reliability characteristics of a table are governed by its
> >  > +   persistence mode.  The default mode is described
> >  > +   here
> >  > +   There are two alternative modes that can be specified during
> >  > +   table creation:
> >  > +   temporary and
> >  > +   unlogged.
> > 
> > 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
> [...]
> +and column_storage is:
> +
> +STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } [ COMPRESSION compression_method ]
> [...]

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 numeric_literal, REM
   Description
 
   
-   CREATE TABLE will create a new, initially empty table
+   CREATE TABLE will create a new, initially empty, table
    in the current database. The table will be owned by the user issuing the
    command.
   

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.

+  
+   The reliability characteristics of a table are governed by its
+   persistence mode.  The default mode is described
+   here
+   There are two alternative modes that can be specified during
+   table creation:
+   temporary and
+   unlogged.
+  

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.

+
+     
+      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.
+     

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

Attached is an updated patch.

Yours,
Laurenz Albe