Re: DOCS: Make the Server Application docs synopses more consistent

On Wed, Mar 12, 2025 at 3:18 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2250(at)gmail(dot)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.
>

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