DOCS - Server Applications [option] should be [option...]

On 2/17/26 2:08 AM, Peter Smith wrote:

Hi.

Make the "option" part consistent in the synopses of all Server Applications:

1. "[option]" should be "[option...]"

Agreed.

2. It should be first

I am not sure that is an improvement. I would rather move things with
less signal towards the end. Also how many examples have we of each?
Most seem to be on the format below which I feel indicates [option...]
is last (but before order dependent arguments like dbname.)

pg_dump [connection-option...] [option...] [dbname]

Andreas

On Wed, Feb 18, 2026 at 7:32 PM Andreas Karlsson <andreas@proxel.se> wrote:

On 2/17/26 2:08 AM, Peter Smith wrote:

Hi.

Make the "option" part consistent in the synopses of all Server Applications:

1. "[option]" should be "[option...]"

Agreed.

2. It should be first

I am not sure that is an improvement. I would rather move things with
less signal towards the end. Also how many examples have we of each?
Most seem to be on the format below which I feel indicates [option...]
is last (but before order dependent arguments like dbname.)

pg_dump [connection-option...] [option...] [dbname]

Thanks for the feedback

The scope of my patch is only the Server Applications [1]https://www.postgresql.org/docs/devel/reference-server.html. Maybe it is
still correct that it is not much of an improvement, but you are
citing examples from Client Applications.

======
[1]: https://www.postgresql.org/docs/devel/reference-server.html

Kind Regards,
Peter Smith.
Fujitsu Australia

On 2/18/26 10:05 AM, Peter Smith wrote:

On Wed, Feb 18, 2026 at 7:32 PM Andreas Karlsson <andreas@proxel.se> wrote:

I am not sure that is an improvement. I would rather move things with
less signal towards the end. Also how many examples have we of each?
Most seem to be on the format below which I feel indicates [option...]
is last (but before order dependent arguments like dbname.)

pg_dump [connection-option...] [option...] [dbname]

Thanks for the feedback

The scope of my patch is only the Server Applications [1]. Maybe it is
still correct that it is not much of an improvement, but you are
citing examples from Client Applications.

Ah, now I see why it is put first in many of the commands. It is to
allow writing the following:

initdb [option...] [ --pgdata | -D ] directory

So I guess I will have to change my mind and say that putting it first
is the least bad option.

Side note: that looks like a bug, shouldn't it be the below?

initdb [option...] [[ --pgdata | -D ] directory]

Andreas

On Thu, Feb 19, 2026 at 8:32 AM Andreas Karlsson <andreas@proxel.se> wrote:

...

Side note: that looks like a bug, shouldn't it be the below?

initdb [option...] [[ --pgdata | -D ] directory]

You will have noticed that I am trying to keep each of these recent
threads/patches narrowly focussed on just one specific problem at a
time.

Last year I had tried fixing many of these same problems at once but
that thread went in too many directions at once, and got bogged down
eventually forgotten about. I hope this focussed thread strategy has a
better chance of success.

~

But yes, I agree with you. The Option description [1]https://www.postgresql.org/docs/devel/app-initdb.html#APP-INITDB-OPTION-PGDATA says "This is
the only information required by initdb, but you can avoid writing it
by..."

Feel free to post a thread / patch for this, or else I can add it to
my list and get to it sometime.

======
[1]: https://www.postgresql.org/docs/devel/app-initdb.html#APP-INITDB-OPTION-PGDATA

Kind Regards,
Peter Smith.
Fujitsu Australia

On 17 Feb 2026, at 02:08, Peter Smith <smithpb2250@gmail.com> wrote:

Make the "option" part consistent in the synopses of all Server Applications:

1. "[option]" should be "[option...]"

Only if the application can take multiple options. pg_controldata can for
example only take a single parameter so [option] is correct there.

2. It should be first

Why? I think it makes more sense to list [option...] after required parameters
just like how pg_upgrade does it. We might not be consistent as is, but I'm
not sure it's a net improvement to always list it first as opposed to what we
have.

--
Daniel Gustafsson

On Tue, Feb 24, 2026 at 1:48 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 17 Feb 2026, at 02:08, Peter Smith <smithpb2250@gmail.com> wrote:

Make the "option" part consistent in the synopses of all Server Applications:

1. "[option]" should be "[option...]"

Only if the application can take multiple options. pg_controldata can for
example only take a single parameter so [option] is correct there.

You are correct. Thanks for pointing it out.

2. It should be first

Why? I think it makes more sense to list [option...] after required parameters
just like how pg_upgrade does it. We might not be consistent as is, but I'm
not sure it's a net improvement to always list it first as opposed to what we
have.

This patch/thread was primarily about #1, which turned out to be
mistaken. The #2 re-ordering part was just done at the same time, but
got it no support

So, I am withdrawing this patch.

======
Kind Regards,
Peter Smith.
Fujitsu Australia