On Wed, Mar 12, 2025 at 3:18 AM David G. Johnston
<david.g.johns...@gmail.com> wrote:
>
> On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2...@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.
>
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
v2-0001-Synopsis-improvements-for-server-applications.patch
Description: Binary data
