Re: Link t the souce code

[Tom Lane]

Alvaro Herrera  writes:
> v3 rewrites the text more aggressively, so that it opens with
> instructions to clone the Git repo, and the released version tarballs
> are mentioned further down.  The bad thing about this one is that in the
> devel version it still talks about files that don't exist; for example
> in branch master it renders as:

>   Alternatively, the released versions can be obtained from the download
>   section of our website: https://www.postgresql.org/ftp/source/. You
>   should get a file named postgresql-15devel.tar.gz or
>   postgresql-15devel.tar.bz2. After you have obtained the file, unpack 
> it:>
>   tar xfa postgresql-15devel.tar.gz
>   This will create a directory postgresql-15devel under the current
directory with the PostgreSQL sources. Change into that directory for
>   the rest of the installation procedure.

ISTM that specifying an exact version number here is rather pointless
anyway.  Could we drop the reference to an exact file name, and write
something like

Alternatively, source code for released versions can be obtained
from the download section of our website:
https://www.postgresql.org/ftp/source/.
Download the postgresql-version.tar.gz or
postgresql-version.tar.bz2 file for the
version you are interested in, then unpack it:
tar xfa postgresql-version.tar.gz
This will create a directory
postgresql-version under the current ...

Admittedly, someone who doesn't grok that
version is a variable might be confused
initially, but I think they'd soon figure it out after seeing the
file names on the server.

regards, tom lane

Re: Link t the souce code

[Alvaro Herrera]

On 2021-May-06, Tom Lane wrote:

> Alvaro Herrera  writes:

> > 3. add a separate paragraph that says to obtain the source from the
> > other dir if it's the development one.
> > I kinda prefer the last one, because then we could also suggest to use a
> > Git repo instead of a tarball, which I suppose is the best option anyway.
> 
> Yeah.  There is text mentioning the git repo further down, but it's
> hardly prominent.  We should move it up and recommend that as the
> best thing for dev work.

Here are two patches.  v2 is a minimal change; it just adds a
parenthical comment about the snapshot tarball and a mention of "the
text below" which is where the source code repository is mentioned.

v3 rewrites the text more aggressively, so that it opens with
instructions to clone the Git repo, and the released version tarballs
are mentioned further down.  The bad thing about this one is that in the
devel version it still talks about files that don't exist; for example
in branch master it renders as:

Alternatively, the released versions can be obtained from the download
section of our website: https://www.postgresql.org/ftp/source/. You
should get a file named postgresql-15devel.tar.gz or
postgresql-15devel.tar.bz2. After you have obtained the file, unpack it:

tar xfa postgresql-15devel.tar.gz
This will create a directory postgresql-15devel under the current
directory with the PostgreSQL sources. Change into that directory for
the rest of the installation procedure.

Now, we *could* make this fully correct by adding
--param pg.version.devel 'true'
(or something like that) to the Makefile, and include paragraphs
conditionally to make it fully correct.  I'm not sure it's worth the
effort.

-- 
Álvaro Herrera   39°49'30"S 73°17'W  —  https://www.EnterpriseDB.com/
>From d000142b596d92463473a28de59a4c9cf78ad771 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera 
Date: Tue, 13 Jul 2021 13:06:54 -0400
Subject: [PATCH v2] Improve installation instructions a bit

Reported-by: Daniel Westermann
Discussion: https://postgr.es/m/gv0p278mb04835aaeacf894617574eb6bd2...@gv0p278mb0483.chep278.prod.outlook.com
---
 doc/src/sgml/installation.sgml | 18 --
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 05b77ec8e6..005d84af3b 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -356,19 +356,17 @@ su - postgres
   
The PostgreSQL  sources can be obtained from the
download section of our
-   website: https://www.postgresql.org/download/;>.  You
+   website: https://www.postgresql.org/ftp/source/;>.  You
should get a file named postgresql-.tar.gz
-   or postgresql-.tar.bz2. After
-   you have obtained the file, unpack it:
+   or postgresql-.tar.bz2.
+   (For the version currently in development, the file is named
+   postgresql-snapshot.tar.bz2 and resides in
+   https://www.postgresql.org/ftp/snapshot/dev/;>;
+   but using the version control repository, below, is recommended.)
+   After you have obtained the file, unpack it:
 
-gunzip postgresql-.tar.gz
-tar xf postgresql-.tar
+tar xfa postgresql-.tar.gz
 
-   (Use bunzip2 instead of gunzip if
-   you have the .bz2 file.  Also, note that most
-   modern versions of tar can unpack compressed archives
-   directly, so you don't really need the
-   separate gunzip or bunzip2 step.)
This will create a directory
postgresql- under the current directory
with the PostgreSQL sources.
-- 
2.30.2

>From fe16cefa81b248352e06253130746f86acd74c72 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera 
Date: Tue, 13 Jul 2021 13:06:54 -0400
Subject: [PATCH v3] Improve installation instructions a bit

Reported-by: Daniel Westermann
Discussion: https://postgr.es/m/gv0p278mb04835aaeacf894617574eb6bd2...@gv0p278mb0483.chep278.prod.outlook.com
---
 doc/src/sgml/installation.sgml | 41 +++---
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 05b77ec8e6..5a900da0a3 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -354,32 +354,37 @@ su - postgres
   Getting the Source
 
   
-   The PostgreSQL  sources can be obtained from the
-   download section of our
-   website: https://www.postgresql.org/download/;>.  You
-   should get a file named postgresql-.tar.gz
-   or postgresql-.tar.bz2. After
-   you have obtained the file, unpack it:
+   The version control repository for PostgreSQL
+   can be obtained from
+   https://git.postgresql.org/gitweb/?p=postgresql.git;a=summary;>;
+   this is the recommended way to obtain the
+   PostgreSQL source code.
+   You can obtain a clone of the repository by running
 
-gunzip postgresql-.tar.gz
-tar xf postgresql-.tar
+git clone https://git.postgresql.org/git/postgresql.git
+
+   This will create a directory 

Re: Minor language edits for PostgreSQL 14 Release Notes

[Bruce Momjian]

On Tue, Jul 20, 2021 at 03:58:00PM +0300, Elena Indrupskaya wrote:
> Hello everyone,
> 
> I noticed minor language inaccuracies/inconsistencies in PostgreSQL 14 Release
> Notes (https://www.postgresql.org/docs/14/release-14.html). A patch to fix 
> them
> is attached.
> One of the replacements changes
> 
> "which reports WAL activity" to
> "to report WAL activity"
> 
> because "to report" is more consistent with the rest of the text (or just add 
> a
> comma before "which").


Thanks. I added a comma as you suggested, and committed.

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

  If only the physical world exists, free will is an illusion.

Re: Manua correction

[Bruce Momjian]

On Tue, Jul 20, 2021 at 11:03:09AM -0400, Tom Lane wrote:
> Bruce Momjian  writes:
> > I really don't understand the use of "(s)" except in place where we are
> > really trying to point out the idea of one or multiple, and I don't see
> > that being significant in these cases --- can you clarify?
> 
> See the example given for regexp_match:
> 
> regression=# select regexp_match('foobarbequebaz', '(bar)(beque)'); 
>  regexp_match 
> --
>  {bar,beque}
> (1 row)
> 
> There's more than one parenthesized subpattern, so you get more than
> one substring in the result.  So I think that change is flat out
> wrong.
> 
> The places where you changed "substring(s)" to "substrings" are maybe
> not flat wrong, but I don't think they're improving the text either.
> IIRC, in most of them you get one match if you didn't use the 'g'
> flag, but possibly multiple matches if you did, and the "substring(s)"
> wording is meant to allude to that without taking the space to spell
> it out explicitly.

I see what you mean --- there can be multiple capture groups, and
multiple match processing if 'g' is used.  I think the text using "(s)"
is too complex, so I spelled out the use 'g' and clarified the case of
multiple groups in a single regex.

Updated patch attached, and I used a larger line context around the
changes to clarify what was being modified.

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

  If only the physical world exists, free will is an illusion.



substring.diff.gz
Description: application/gzip

Re: Manua correction

[Tom Lane]

Bruce Momjian  writes:
> On Thu, Jul 15, 2021 at 11:12:38PM -0400, Tom Lane wrote:
>> At least two of these changes are flat out wrong.  The places
>> that explicitly mention "substring(s)" are not doing so because
>> we failed to think about what that meant.

> I really don't understand the use of "(s)" except in place where we are
> really trying to point out the idea of one or multiple, and I don't see
> that being significant in these cases --- can you clarify?

See the example given for regexp_match:

regression=# select regexp_match('foobarbequebaz', '(bar)(beque)'); 
 regexp_match 
--
 {bar,beque}
(1 row)

There's more than one parenthesized subpattern, so you get more than
one substring in the result.  So I think that change is flat out
wrong.

The places where you changed "substring(s)" to "substrings" are maybe
not flat wrong, but I don't think they're improving the text either.
IIRC, in most of them you get one match if you didn't use the 'g'
flag, but possibly multiple matches if you did, and the "substring(s)"
wording is meant to allude to that without taking the space to spell
it out explicitly.

regards, tom lane

Minor language edits for PostgreSQL 14 Release Notes

[Elena Indrupskaya]

Hello everyone,

I noticed minor language inaccuracies/inconsistencies in PostgreSQL 14 
Release Notes (https://www.postgresql.org/docs/14/release-14.html). A 
patch to fix them is attached.

One of the replacements changes

"which reports WAL activity" to
"to report WAL activity"

because "to report" is more consistent with the rest of the text (or 
just add a comma before "which").


--
Elena Indrupskaya
Lead Technical Writer
Postgres Professional http://www.postgrespro.comtext. 

diff --git a/doc/src/sgml/release-14.sgml b/doc/src/sgml/release-14.sgml
index ecd074361c6..4f0437f87d9 100644
--- a/doc/src/sgml/release-14.sgml
+++ b/doc/src/sgml/release-14.sgml
@@ -784,7 +784,7 @@ Author: Peter Geoghegan 
 

 Reduce the default value of  to better reflects current
+linkend="guc-vacuum-cost-page-miss"/> to better reflect current
 hardware capabilities (Peter Geoghegan)

   
@@ -1441,7 +1441,7 @@ Author: Fujii Masao 

 Add system view pg_stat_wal
-which reports WAL activity (Masahiro Ikeda)
+to report WAL activity (Masahiro Ikeda)

   
 
@@ -1936,7 +1936,7 @@ Author: Michael Paquier 
   
 
   
-   Previously these functions could only be executed by super-users,
+   Previously these functions could only be executed by superusers,
and this is still the default.
   
  
@@ -2599,7 +2599,7 @@ Author: Tom Lane 
   
 
   
-   Floating point data types already supported these.
+   Floating-point data types already supported these.
   
  
 
@@ -2610,7 +2610,7 @@ Author: Tom Lane 
 -->
 
   
-   Improve the accuracy of floating point computations involving
+   Improve the accuracy of floating-point computations involving
infinity (Tom Lane)
   
  

Re: Headers for each index

[Jürgen Purtz]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/13/indexes-types.html
Description:

For easier visual navigation could you please add headers or color the
different types of indexes? At the moment, one needs to read the whole
document or do search in the page to find the available indexes.

Thanks a ton!


The look has changed in version 14 in a way that hopefully matches 
your suggestion: https://www.postgresql.org/docs/14/indexes-types.html


--

Jürgen Purtz