On Wed, Mar 12, 2025 at 3:18 AM David G. Johnston <[email protected]> wrote: > > On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <[email protected]> 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
