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(at)eisentraut(dot)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