Better help output for pgbench -I init_steps

On 12.07.23 09:42, Gurjeet Singh wrote:

These two variants show the two extremes; bare minimum vs. everything
but the kitchen sink. So one may feel the need to find a middle ground
and provide a "sufficient, but not too much" variant. I have attempted
that in variants 3 and 4; also attached.

If you end up with variant 3 or 4, please use double quotes instead of
single quotes.

On 2023-Jul-12, Gurjeet Singh wrote:

The init-steps are severely under-documented in pgbench --help output.
I think at least a pointer to the the pgbench docs should be mentioned
in the pgbench --help output; an average user may not rush to read the
code to find the explanation, but a hint to where to find more details
about what the letters in --init-steps mean, would save them a lot of
time.

Agreed.

I would do it the way `pg_waldump --rmgr=list` or `psql
--help=variables` are handled: they give you a list of what is
supported. You don't have to put the list in the main --help output.

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"El sentido de las cosas no viene de las cosas, sino de
las inteligencias que las aplican a sus problemas diarios
en busca del progreso." (Ernesto Hernández-Novich)

On Wed, Jul 12, 2023 at 3:08 AM Peter Eisentraut <peter@eisentraut.org> wrote:

On 12.07.23 09:42, Gurjeet Singh wrote:

These two variants show the two extremes; bare minimum vs. everything
but the kitchen sink. So one may feel the need to find a middle ground
and provide a "sufficient, but not too much" variant. I have attempted
that in variants 3 and 4; also attached.

If you end up with variant 3 or 4, please use double quotes instead of
single quotes.

Will do.

I believe you're suggesting this because in the neighboring help text
the string literals use double quotes. I see that other utilities,
such as psql also use double quotes in help text.

If there's a convention, documented somewhere in our sources, I'd love
to know and learn other conventions.

Best regards,
Gurjeet
http://Gurje.et

On 12.07.23 19:47, Gurjeet Singh wrote:

If you end up with variant 3 or 4, please use double quotes instead of
single quotes.

Will do.

I believe you're suggesting this because in the neighboring help text
the string literals use double quotes. I see that other utilities,
such as psql also use double quotes in help text.

If there's a convention, documented somewhere in our sources, I'd love
to know and learn other conventions.

https://www.postgresql.org/docs/devel/error-style-guide.html#ERROR-STYLE-GUIDE-QUOTATION-MARKS

On 12.07.23 15:41, Alvaro Herrera wrote:

On 2023-Jul-12, Gurjeet Singh wrote:

The init-steps are severely under-documented in pgbench --help output.
I think at least a pointer to the the pgbench docs should be mentioned
in the pgbench --help output; an average user may not rush to read the
code to find the explanation, but a hint to where to find more details
about what the letters in --init-steps mean, would save them a lot of
time.

Agreed.

I would do it the way `pg_waldump --rmgr=list` or `psql
--help=variables` are handled: they give you a list of what is
supported. You don't have to put the list in the main --help output.

I think I prefer variant 2. Currently we only have 8 steps, so it might
be overkill to separate them out into a different option.

The following review has been posted through the commitfest application:
make installcheck-world: not tested
Implements feature: tested, passed
Spec compliant: not tested
Documentation: not tested

Hello,

I've reviewed all 4 of your patches, each one applies and builds correctly.

I think I prefer variant 2. Currently, we only have 8 steps, so it might
be overkill to separate them out into a different option.

+1 to this from Peter. Variant 2 is nicely formatted with lots of information which I feel better solves the problem this patch is trying to address.
Both versions 3 and 4 are a bit too jumbled for my liking without adding anything significant, even the shortened version 4.

If we were to go with variant 1 however, I think it would add more to have a link to the pgbench documentation that refers to the different init steps. Perhaps on a new line just under where it says "see pgbench documentation for a description of these steps".

Overall good patch, I'm a firm believer that more information is always better than less.

Tristen
---------------
Software Engineer
HighGo Software Inc. (Canada)
tristen.raab@highgo.ca
www.highgo.ca

On 22.09.23 22:01, Tristen Raab wrote:

The following review has been posted through the commitfest application:
make installcheck-world: not tested
Implements feature: tested, passed
Spec compliant: not tested
Documentation: not tested

Hello,

I've reviewed all 4 of your patches, each one applies and builds correctly.

I think I prefer variant 2. Currently, we only have 8 steps, so it might
be overkill to separate them out into a different option.

+1 to this from Peter. Variant 2 is nicely formatted with lots of information which I feel better solves the problem this patch is trying to address.

Committed variant 2. I just changed the initial capitalization of the
sentences to be more consistent with the surrounding text.