Misleading

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/static/pgupgrade.html
Description:

Hello,

Please correct following part of pg_upgrade documentation:
`You can also specify user and port values, and whether you want the data
linked instead of copied (the default).`

It is not clear what is the default option. If you read the whole sentence,
then context might be misinterpreted to `data linked instead of copied` is
default but you meant that copying is default. Please correct this as it is
confusing and can lead someone to big troubles.

My suggestion:
- completely omit confusing default word:
`You can also specify user and port values, and whether you want the data
linked instead of copied.`

Thank you.

Cheers,
Marek

On 3/28/17 07:02, marek(dot)cvoren(at)gmail(dot)com wrote:
> Please correct following part of pg_upgrade documentation:
> `You can also specify user and port values, and whether you want the data
> linked instead of copied (the default).`
>
> It is not clear what is the default option. If you read the whole sentence,
> then context might be misinterpreted to `data linked instead of copied` is
> default but you meant that copying is default. Please correct this as it is
> confusing and can lead someone to big troubles.
>
> My suggestion:
> - completely omit confusing default word:
> `You can also specify user and port values, and whether you want the data
> linked instead of copied.`

It's debatable whether that sentence is unclear, I think, but the change
you propose actually loses the information about what mode is the
default, which wouldn't be good.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Wed, Apr 5, 2017 at 12:28:46AM -0400, Peter Eisentraut wrote:
> On 3/28/17 07:02, marek(dot)cvoren(at)gmail(dot)com wrote:
> > My suggestion:
> > - completely omit confusing default word:
> > `You can also specify user and port values, and whether you want the data
> > linked instead of copied.`
>
> It's debatable whether that sentence is unclear, I think, but the change
> you propose actually loses the information about what mode is the
> default, which wouldn't be good.

I have applied the attached doc patch to clarify this.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +