Minor improvement in sentences to enhance readability

[Muhammad Ikram]

Here are some minor change suggestions which may help in improving
readability.
It is your prerogative to accept or reject

Doc : https://www.postgresql.org/docs/17/install-make.html

*Actual Text*

If you are upgrading an existing system be sure to read Section 18.6
, which has instructions
about upgrading a cluster.

*Proposed*
If you are upgrading an existing system, be sure to read Section 18.6
, which has instructions
about upgrading a cluster.

Hi,

Suggesting minor improvements in
https://www.postgresql.org/docs/17/install-make.html
to enhance readability.


*Change*
  Added comma between  "system and be"
--

To keep the text consistent, built might be replaced by build.

*Actual Text*

If you *built* with debugging support, stripping will effectively remove
the debugging support

*Proposed*

If you *build* with debugging support, stripping will effectively remove
the debugging support

*Change*
  Replaced built by build

*Actual Text*
All files will be installed under /usr/local/pgsql by default.

*Proposed*
 By default, all files will be installed under /usr/local/pgsql.

*Actual Text*

(Remember to use GNU make.) The build will take a few minutes depending on
your hardware.
*Proposed*
The build will take a few minutes, depending on your hardware (remember to
use GNU make).


*Actual Text*

use ./configure --help to get one that is

*Proposed*

use ./configure --help to see all options.

or

use ./configure --help to list all options.


Regards,
Muhammad Ikram,
Bitnine Global

8.12. UUID Type

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/datatype-uuid.html
Description:

Is this the right sentence? "use of upper-case digits"
>>PostgreSQL also accepts the following alternative forms for input: use of
upper-case digits

Re: 8.12. UUID Type

[Laurenz Albe]

On Thu, 2024-06-13 at 08:59 +, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/16/datatype-uuid.html
> Description:
> 
> Is this the right sentence? "use of upper-case digits"
> > > PostgreSQL also accepts the following alternative forms for input: use of 
> > > upper-case digits

Hexadecimal digits, also known as letters.

Yours,
Laurenz Albe

Re: 8.12. UUID Type

[hubert depesz lubaczewski]

On Thu, Jun 13, 2024 at 08:59:18AM +, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/16/datatype-uuid.html
> Description:
> 
> Is this the right sentence? "use of upper-case digits"
> >>PostgreSQL also accepts the following alternative forms for input: use of
> upper-case digits


I'd say so. Previous paragraph says:

"…sequence of lower-case hexadecimal digits…"

So digits are not only 0-9, but also a-f. And this can be upper or lower
case.

Best regards,

depesz

Re: 28.4.4. Progress Reporting phase status

[Alvaro Herrera]

On 2024-Jun-03, Euler Taveira wrote:

> On Thu, May 30, 2024, at 12:50 PM, PG Doc comments form wrote:
> > I noticed that in "28.4.4. Progress Reporting" chapter for
> > `pg_stat_progress_create_index`, the  "Table 28.43. CREATE INDEX Phases" may
> > be misleading as phase displayed for "building index" is often more
> > detailed. 
> > I found in this presentation[1] (slide 20) what seems to be the exact status
> > displayed by the table while creating the index. 
> > Maybe documentation table displaying all status could be extended to display
> > the following status:
> 
> The description is accurate. Since this step (building index) is AM-specific, 
> it
> shouldn't contain the additional information (after the semicolon).

However, maybe Eve is right that we should have these steps:

> > - building index: initializing [2]
> > - building index: scanning table
> > - building index: sorting live tuples
> > - building index: sorting dead tuples
> > - building index: loading tuples in tree

somewhere in the AM-specific doc pages,
https://www.postgresql.org/docs/devel/btree.html
and perhaps we can link to that from the progress-report chapter.

(Not really related, but: I think the per-index-AM subsections in 
https://www.postgresql.org/docs/devel/indexes-types.html
should have forward-links to the appendix sections on them.)

> You can certainly obtain the build phases from all access
> methods with a query like:
> 
> WITH amidx AS (
> SELECT oid, amname FROM pg_am WHERE amtype = 'i')
> SELECT a.amname, pg_indexam_progress_phasename(a.oid, i)
> FROM amidx a, generate_series(0, 100) i
> WHERE pg_indexam_progress_phasename(a.oid, i) IS NOT NULL
> ORDER BY a.amname, i;

Heh, only btrees show up there.  Sad.  I wonder to what extent would it
be useful for the other index AMs to report sub-phases of index
creation.  It should be pretty simple to implement ...

-- 
Álvaro HerreraBreisgau, Deutschland  —  https://www.EnterpriseDB.com/
"La gente vulgar sólo piensa en pasar el tiempo;
el que tiene talento, en aprovecharlo"

Re: 8.12. UUID Type

[Alvaro Herrera]

On 2024-Jun-13, Laurenz Albe wrote:

> On Thu, 2024-06-13 at 08:59 +, PG Doc comments form wrote:
> > Page: https://www.postgresql.org/docs/16/datatype-uuid.html
> > Description:
> > 
> > Is this the right sentence? "use of upper-case digits"
> > > > PostgreSQL also accepts the following alternative forms for input: use 
> > > > of upper-case digits
> 
> Hexadecimal digits, also known as letters.

Everybody knows that ! is an uppercase 1, right?
/s

-- 
Álvaro Herrera   48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
#error "Operator lives in the wrong universe"
  ("Use of cookies in real-time system development", M. Gleixner, M. Mc Guire)