Обсуждение: Better help output for pgbench -I init_steps
These patches were created during an unrelated discussion about pgbench. Please see emails [1] - [6] linked below, for the past discussion. In brief: > $ pgbench -i -I dtGvp -s 500 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. Please see attached 4 variants of the patch. Variant 1 simply tells the reader to consult pgbench documentation. The second variant provides a description for each of the letters, as the documentation does. The committer can pick the one they find suitable. The text ", in the specified order" is an important detail, that should be included irrespective of the rest of the patch. My preference would be to use the first variant, since the second one feels too wordy for --help output. I believe we'll have to choose between these two; the alternatives will not make anyone happy. 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. The third variant does away with the list of steps, and uses a paragraph to describe the letters. And the fourth variant makes that paragraph terse. In the order of preference I'd choose variant 1, then 2. Variants 3 and 4 feel like a significant degradation from variant 2. Attached samples.txt shows the snippets of --help output of each of the variants/patches, for comparison. In [6] below, Tristan showed preference for the second variant. [1] My complaint about -I initi_steps being severely under-documented in --help output https://www.postgresql.org/message-id/CABwTF4XMdHTxemhskad41Vj_hp2nPgifjwegOqR52_8-wEbv2Q%40mail.gmail.com [2] Tristan Partin agreeing with the complaint, and suggesting a patch would be welcome https://www.postgresql.org/message-id/CT8BC7RXT33R.3CHYIXGD5NVHK%40gonk [3] Greg Smith agreeing and saying he'd welcome a few more words about the init_steps in --help output https://www.postgresql.org/message-id/CAHLJuCUp5_VUo%2BRJ%2BpSnxeiiZfcstRtTubRP8%2Bu8NEqmrbp4aw%40mail.gmail.com [4] First set of patches https://www.postgresql.org/message-id/CABwTF4UKv43ZftJadsxs8%3Da07BmA1U4RU3W1qbmDAguVKJAmZw%40mail.gmail.com [5] Second set of patches https://www.postgresql.org/message-id/CABwTF4Ww42arY1Q88_iaraVLxqSU%2B8Yb4oKiTT5gD1sineog9w%40mail.gmail.com [6] Tristan showing preference for the second variant https://www.postgresql.org/message-id/CTBN5E2K2YSJ.3QYXGZ09JZXIW%40gonk +CC Tristan Partin and Greg Smith, since they were involved in the initial thread. Best regards, Gurjeet http://Gurje.et
Вложения
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 thispatch is trying to address. Both versions 3 and 4 are a bit too jumbled for my liking without adding anything significant, even the shortened version4. If we were to go with variant 1 however, I think it would add more to have a link to the pgbench documentation that refersto the different init steps. Perhaps on a new line just under where it says "see pgbench documentation for a descriptionof 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 thispatch is trying to address. Committed variant 2. I just changed the initial capitalization of the sentences to be more consistent with the surrounding text.