Thread: Re: DOCS: Make the Server Application docs synopses more consistent
On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2250@gmail.com> wrote:
[1] initdb [option...] [ --pgdata | -D ] directory
[2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
[3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
[4] pg_controldata [option] [[ -D | --pgdata ]datadir]
[5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
[6] pg_ctl (the many synopses here don't give all the switch
alternatives, it would be too much...)
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
--pgdata ]datadir
[8] pg_rewind [option...] { -D | --target-pgdata } directory {
--source-pgdata=directory | --source-server=connstr }
[9] pg_test_fsync [option...]
[10] pg_test_timing [option...]
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
[12] pg_waldump [option...] [startseg [endseg]]
[13] pg_walsummary [option...] [file...]
Here are some guidelines we should add to [1].
I don't feel listing both short and long form args is a good use of space - and the { | } impairs readability. The short form combined with, usually, a decent replaceable name, shows the reader the common interactive usage and they can find the long forms in the Options section. Maybe use long forms for value-less options since those don't get the argname hint.
The non-space between option and its value reduces readability. IIUC a space in between doesn't impact correctness so I say go for readability. This becomes more pronounced with the first items since it is only marginally readable now because there is always a } or ] before the replaceable. Though this may involve fighting the markup a bit...I haven't experimented yet (pg_rewind managed it...).
The first listed command should probably only include mandatory options. When there are multiple combinations of mandatory options show multiple commands, one for each variant. Use examples to showcase idiomatic usage patterns with descriptions. There is room to argue exceptions to be listed also in Synopsis.
Establish the convention of datadir as the replaceable name. Possibly do the same for other common items.
We should have a reference page (near [1] listing DocBook elements and our guidelines for how/where to use them.
In any case, details aside, modifying [1] with whatever is agreed to (and making changes to conform) is something I agree should happen.
David J.
On Wed, Mar 12, 2025 at 3:18 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2250@gmail.com> wrote:
>>
>> [1] initdb [option...] [ --pgdata | -D ] directory
>> [2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
>> [3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
>> [4] pg_controldata [option] [[ -D | --pgdata ]datadir]
>> [5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
>> --pgdata }datadir { -P | --publisher-server }connstr
>> [6] pg_ctl (the many synopses here don't give all the switch
>> alternatives, it would be too much...)
>> [7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
>> --pgdata ]datadir
>> [8] pg_rewind [option...] { -D | --target-pgdata } directory {
>> --source-pgdata=directory | --source-server=connstr }
>> [9] pg_test_fsync [option...]
>> [10] pg_test_timing [option...]
>> [11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
>> newconfigdir [option...]
>> [12] pg_waldump [option...] [startseg [endseg]]
>> [13] pg_walsummary [option...] [file...]
>>
>
> Here are some guidelines we should add to [1].
>
> I don't feel listing both short and long form args is a good use of space - and the { | } impairs readability. The
shortform combined with, usually, a decent replaceable name, shows the reader the common interactive usage and they can
findthe long forms in the Options section. Maybe use long forms for value-less options since those don't get the
argnamehint.
>
> The non-space between option and its value reduces readability. IIUC a space in between doesn't impact correctness
soI say go for readability. This becomes more pronounced with the first items since it is only marginally readable now
becausethere is always a } or ] before the replaceable. Though this may involve fighting the markup a bit...I haven't
experimentedyet (pg_rewind managed it...).
>
> The first listed command should probably only include mandatory options. When there are multiple combinations of
mandatoryoptions show multiple commands, one for each variant. Use examples to showcase idiomatic usage patterns with
descriptions. There is room to argue exceptions to be listed also in Synopsis.
>
> Establish the convention of datadir as the replaceable name. Possibly do the same for other common items.
>
> We should have a reference page (near [1] listing DocBook elements and our guidelines for how/where to use them.
>
> In any case, details aside, modifying [1] with whatever is agreed to (and making changes to conform) is something I
agreeshould happen.
>
Hi David.
Thanks for taking an interest in this thread.
I've made some updates and attached the v2 patch.
======
CHANGE SUMMARY
There are some discussion points among these changes as well as other
TODO items to check I haven't broken anything.
[1] initdb [option...] [ --pgdata | -D ] directory
- removed the short/long option variations
- cleanup the tags
- changed replaceable 'directory' to 'datadir' in the synopsis and in
the options list
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]"
[2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
- no changes
[3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
- removed the short/long option variations
- cleanup the tags
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[4] pg_controldata [option] [[ -D | --pgdata ]datadir]
- removed the short/long option variations
- cleanup the tags
- some <option> should be <replaceable>
- the "[option]" should be "[option...]"
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
- TODO. The page structure looks strange. There should be an "Options"
section to describe -D, -V, and -?
[5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
- removed the short/long option variations
- cleanup the tags
- rearranged so -D comes first (same as most other commands)
- make the "-D datadir" optional "[-D datadir]"
- change 'directory' to 'datadir' in the options list so it matches the synopsis
- change the order of the options list to match
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[6] pg_ctl (the many synopses here don't give all the switch
alternatives, it would be too much...)
- no changes
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
--pgdata ]datadir
- removed the short/long option variations
- cleanup the tags
- TODO. Looks a bit strange with "[options...]" not shown first.
[8] pg_rewind [option...] { -D | --target-pgdata } directory {
--source-pgdata=directory | --source-server=connstr }
- removed the short/long option variations
- cleanup the tags
- make the "{-D datadir}" to be optional "[-D datadir]"
- change 'directory' to 'datadir' in the synopsis and in the options
list (for --D and for --source-pgdata)
- TODO. Was it OK to make the "[-D datadir]" optional like all others?
The page does not mention PGDATA.
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[9] pg_test_fsync [option...]
- no changes
[10] pg_test_timing [option...]
- no changes
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
- removed the short/long option variations
- cleanup the tags
- made all the option to be optional because the page says they can
all use environment variable defaults.
- TODO. Looks a bit strange with "[options...]" not shown first.
[12] pg_waldump [option...] [startseg [endseg]]
- change the <option> tags to be <replaceable>
[13] pg_walsummary [option...] [file...]
- Fixed a typo "found with" -> "found in"
- Change 'file' to 'filename' in the synopsis
- Add the missing entry in the options list to describe the 'filename'.
~~~
I've modified the DOCS guidelines as suggested by adding a few recommendations.
~~~
OTHER QUESTIONS
- Should we use class="parameter" for all the <replaceable> tags?
Currently, some do, but most do not.
~~~
BTW, the scope of this thread is originally only the *server*
application pages, but all the *client* applications might be impacted
if we applied the same rules there.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachment
On Wednesday, March 12, 2025, Peter Smith <smithpb2250@gmail.com> wrote:
I've made some updates and attached the v2 patch.
Thanks. Full review later.
Pg_controldata
- TODO. The page structure looks strange. There should be an "Options"
section to describe -D, -V, and -?
Agreed.
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
- TODO. Looks a bit strange with "[options...]" not shown first.
Yeah, need to fix that.
[8] pg_rewind [option...] { -D | --target-pgdata } directory
- TODO. Was it OK to make the "[-D datadir]" optional like all others?
The page does not mention PGDATA.
My take on this is that the presence of environment variables doesn’t impact whether a given CLI option is shown optional or mandatory. We are, in effect, communicating that “datadir” must be specified for this command. And then choosing one of the ways of specifying it. The reader can use the indicated short-form -D, the long-form —pgdata if it exists, or the DATADIR environment variable (this applies to any option, not just datadir) as they desire. In short, most/all of these should show “-D datadir” without [ ].
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
- made all the option to be optional because the page says they can
all use environment variable defaults.
See note above regarding environment variables.
- TODO. Looks a bit strange with "[options...]" not shown first.
Should be moved.
OTHER QUESTIONS
- Should we use class="parameter" for all the <replaceable> tags?
Currently, some do, but most do not.
I’d probably document that they should have that class but leave the bulk cleanup of existing content for a separate patch.
~~~
BTW, the scope of this thread is originally only the *server*
application pages, but all the *client* applications might be impacted
if we applied the same rules there.
Yeah, noticed that yesterday. I don’t see a reason why the same policy shouldn’t apply to both subsets. I wouldn’t require everything has to be changed right now though. Perfectly happy to ask for people specifically familiar with these applications to modify the pages under the new policy and try to divvy up the work. Then pickup what doesn’t get done.
David J.
On Wednesday, March 12, 2025, David G. Johnston <david.g.johnston@gmail.com> wrote:
My take on this is that the presence of environment variables doesn’t impact whether a given CLI option is shown optional or mandatory. We are, in effect, communicating that “datadir” must be specified for this command. And then choosing one of the ways of specifying it. The reader can use the indicated short-form -D, the long-form —pgdata if it exists, or the DATADIR environment variable (this applies to any option, not just datadir) as they desire. In short, most/all of these should show “-D datadir” without [ ].
Expanding on this a bit. Write the synopsis as if no environment variables are set.
Generally, if the application itself defines the default value do not list the option in the primary synopsis entry at all. If the application takes an option’s default value from the OS environment by a means other than an optional environment variable then show the option in the primary synopsis entry but mark it as optional.
Connection options can have their own rules; which means we don’t need to be specifying -U and -d everywhere when we deal with client applications. Though maybe we should?
David J.