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.
