Re: PostgreSQL 15 minor documentation improvements

[Maxim Yablokov]

On Wed, Aug 17, 2022 at 06:09:13PM +0300, Максим Яблоков wrote:

I have prepared a small patch with possible changes of these places, and
also a separate patch with some improvements concerning missed/inapt tags.
Please have a look.

archive_command is used only when archive_library is not set AFAIK,
but an archive_library could also freely use an archive_command if it
wishes to.  But, yes, I agree that the current wording in backup.sgml
is kind of confusing because of this reason, so I am fine to have a
reference to both archive_library *and* archive_command in this area
of the docs.

  All WAL records required for the backup must contain sufficient full-page 
writes,
  which requires you to enable full_page_writes on the 
primary and
-not to use a tool in your archive_library to remove
-full-page writes from WAL files.
+not to use a tool to remove full-page writes from WAL files.

Hmm.  My opinion here is to do a simplification, and remove simply the
last part of the paragraph about tools that manipulate WAL files
as the first sentence makes it clear, in my opinion, that if those
FPWs are not around the server could become kaput.

Thanks, new patch is attached.

Most of the changes in PGSQL15_tags_fix.patch seem right to me.
Still, you'd better check that the docs compile, as of:


--- a/doc/src/sgml/basebackup-to-shell.sgml
+++ b/doc/src/sgml/basebackup-to-shell.sgml
@@ -12,9 +12,9 @@
called shell. This makes it possible to run
pg_basebackup --target=shell or, depending on how this
module is configured,
-  pg_basebackup --target=shell:DETAIL_STRING, and cause
-  a server command chosen by the server administrator to be executed for
-  each tar archive generated by the backup process. The command will receive
+  pg_basebackup 
--target=shell:DETAIL_STRING,

I am pretty sure that this line is going to cause a compilation
failure of the docs.  Anyway, this should be use a  markup,
no?

Yeah, sorry about that, I fixed it in the new patch.
As for the  tag, it is written above:
pg_basebackup --target=shell
And also in backup.sgml there is the following:
 createdb -T template0 class="parameter">dbname

So I believe that we can keep  here.

Thanks a lot!

--
Michael

--
Best regards,
Maxim Yablokov
Technical writer-translator
Postgres Professional diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 73a774d3d7f..2a64f601ffe 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -945,11 +945,11 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true);
  On a standby, archive_mode must be always in order
  for pg_backup_stop to wait.
  Archiving of these files happens automatically since you have
- already configured archive_library. In most cases this
- happens quickly, but you are advised to monitor your archive
+ already configured archive_library or archive_command.
+ In most cases this happens quickly, but you are advised to monitor your archive
  system to ensure there are no delays.
- If the archive process has fallen behind
- because of failures of the archive library, it will keep retrying
+ If the archive process has fallen behind because of failures of the archive library or
+ archive command, it will keep retrying
  until the archive succeeds and the backup is complete.
  If you wish to place a time limit on the execution of
  pg_backup_stop, set an appropriate
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 56ac7b754be..a5f63bd6609 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -101,9 +101,7 @@ PostgreSQL documentation
 
  
   All WAL records required for the backup must contain sufficient full-page writes,
-  which requires you to enable full_page_writes on the primary and
-  not to use a tool in your archive_library to remove
-  full-page writes from WAL files.
+  which requires you to enable full_page_writes on the primary.
  
 

diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml
index 40cab29b247..28ace574dd5 100644
--- a/doc/src/sgml/adminpack.sgml
+++ b/doc/src/sgml/adminpack.sgml
@@ -22,8 +22,9 @@
   functions in , which
   provide read-only access.)
   Only files within the database cluster directory can be accessed, unless the
-  user is a superuser or given privileges of one of the pg_read_server_files,
-  or pg_write_server_files roles, as appropriate for the function, but either a
+  user is a superuser or given privileges of one of the
+  pg_read_server_files or pg_write_server_files
+  roles, as appropriate for the function, but either a
   relative or absolute path is allowable.
  
 
diff --git a/doc/src/sgml/archive-modules.sgml b/doc/src/sgml/archive-modules.sgml
index ee70e922490..37b1fc061ed 100644
--- a/doc/src/sgml/archive-modules.sgml
+++ b/doc/src/sgml/archive-modules.sgml
@@ 

Re: CREATE INDEX...USING

[Bruce Momjian]

On Wed, Aug 17, 2022 at 11:21:58PM -0400, Bruce Momjian wrote:
> On Wed, Aug 17, 2022 at 05:11:23PM -0400, Jeff Janes wrote:
> > That looks good to me.  But now looking over the linked pages more, it seems
> > like https://www.postgresql.org/docs/current/indexes-types.html was never
> > changed to admit the possibility of custom index access methods (like bloom)
> 
> Uh, bloom is in /contrib, so we wouldn't mention that in the main docs,
> I think.  However, it might be nice to mention you can add others.
> 
> > and neither was the 'replaceable class="parameter">method' section of 
> > https://
> > www.postgresql.org/docs/current/sql-createindex.html.
> 
> Yes, seems we should say that you can install your own methods that can
> be used, e.g., bloom.
> 
> > Also, is it odd that we say essentially the same thing for literal USING as 
> > we
> > say for the replaceable /method/?
> 
> Well, this is embarrassing.  Someone reported there was no mention of
> USING in the CREATE INDEX docs, and I didn't see it either, so I added
> it.
> 
> However, CREATE INDEX just lists the parameters, not the keywords, so it
> was already there as 'method', as you mentioned above.  I will just
> remove the USING section I recently added.

I wrote the attached patch to address the issues above.

-- 
  Bruce Momjian  https://momjian.us
  EDB  https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 2a70e02f7c..0c3fcfd62f 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -117,7 +117,8 @@ CREATE INDEX test1_id_index ON test1 (id);
 
   
PostgreSQL provides several index types:
-   B-tree, Hash, GiST, SP-GiST, GIN and BRIN.
+   B-tree, Hash, GiST, SP-GiST, GIN, BRIN, and the extension bloom.
Each index type uses a different
algorithm that is best suited to different types of queries.
By default, the CREATE
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 944fdb4b09..40986aa502 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -149,18 +149,6 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
  
 
- 
-  USING
-  
-   
-The optional USING clause specifies an index
-type as described in .  If not
-specified, a default index type will be used based on the
-data types of the columns.
-   
-  
- 
-
  
   INCLUDE
   
@@ -250,8 +238,9 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
 The name of the index method to be used.  Choices are
 btree, hash,
-gist, spgist, gin, and
-brin.
+gist, spgist, gin,
+brin, or user-installed access methods like
+bloom.
 The default method is btree.

   

Re: max_sync_workers_per_subscription

[Bruce Momjian]

On Tue, Oct 26, 2021 at 11:06:26AM -0400, Bruce Momjian wrote:
> On Tue, Oct 19, 2021 at 08:59:08AM +, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> > 
> > Page: https://www.postgresql.org/docs/13/logical-replication-config.html
> > Description:
> > 
> > max_sync_workers_per_subscription option is not added.
> 
> Can someone comment on this doc suggestion?

I looked at this --- max_sync_workers_per_subscription is really for
parallelism during the initial copy.  It doesn't seem like something
that requires changes, which I think is why it is not listed.

-- 
  Bruce Momjian  https://momjian.us
  EDB  https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

Re: [PATCH] doc/queries.sgml: add missing comma

[Bruce Momjian]

On Tue, Oct 19, 2021 at 06:41:54PM -0700, David G. Johnston wrote:
> On Tue, Oct 19, 2021 at 2:33 PM Tom Lane  wrote:
> 
> Drew DeVault  writes:
> > Minor grammatical fix.
> 
> Hmm, I'm not sure that reads any better than before.
> 
> >     
> > -    Strictly speaking, this process is iteration not recursion, but
> > +    Strictly speaking, this process is iteration, not recursion, but
> >      RECURSIVE is the terminology chosen by the SQL
> standards
> 
> ... although I think this text is mine, so naturally I'd think
> that.  Anyone else have an opinion?
> 
> 
> 
> If I read that aloud to myself there is a comma after iteration.
> 
> That said, given that a comma and a "but" later we use the word "RECURSIVE" 
> the
> clarification that the process isn't recursion seems redundant.  If one knows
> what it means to be "recursive" then they will understand the juxtaposition of
> "iteration" and "recursive" just fine.  If they do not, I don't think adding
> the word "recursion" is going to make much difference.
> 
> Thus:
> Strictly speaking, this process is iteration, but RECURSIVE
> is the terminology chosen by the SQL standards committee."
> 
> Because the above sounds just fine, I'd argue that if one does leave "not
> recursion" it should be set off by a comma.

I went with new wording, which should make this even clearer;  patch
attached.

-- 
  Bruce Momjian  https://momjian.us
  EDB  https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 516fbcbf37..51b752709e 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -2172,7 +2172,7 @@ SELECT sum(n) FROM t;
 
   

-Strictly speaking, this process is iteration not recursion, but
+Strictly speaking, this process is iterative, not recursive, but
 RECURSIVE is the terminology chosen by the SQL standards
 committee.

Re: PostgreSQL 15 minor documentation improvements

[Michael Paquier]

On Thu, Aug 18, 2022 at 12:46:41PM +0300, Maxim Yablokov wrote:
> Yeah, sorry about that, I fixed it in the new patch.
> As for the  tag, it is written above:
> pg_basebackup --target=shell
> And also in backup.sgml there is the following:
>  createdb -T template0  class="parameter">dbname
> So I believe that we can keep  here.

Well, both are commands, but it is true that we use both patterns in
the docs, still I have switched both to use , and applied the
patch after tweaking things a bit.

(Note as well that the various SIG* use  instead of
, but I have not bothered about changing that).
--
Michael


signature.asc
Description: PGP signature