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

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.

David J.

[1]
https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES