Thread: -V, --version -- deprecated?
The "--help" output for most of the binaries we install does not include the "-V" option (just its alias, --version). Is this intentional? (Note that we still document this option in the reference pages for some commands, and initdb's help output does include "-V".) Speaking of command-line options, "--version" and "--help" aren't documented in a lot of command reference pages. Is there a good reason why? -Neil
Neil Conway wrote: > The "--help" output for most of the binaries we install does not > include the "-V" option (just its alias, --version). Is this > intentional? > > (Note that we still document this option in the reference pages for > some commands, and initdb's help output does include "-V".) --help and --version are the standard options that are supported everywhere. In the era before we had long options everywhere, we implemented -V as an alternative in some programs, in particular those in and around initdb, because of the version cross-checking it does using those options. At one point, long options where broken on some BSD versions. I don't know what became of that, but if we don't have new information it might be safest to leave things where they are. Hence, the -V option is not the preferred public interface, so it's not prominently documented, which may or may not be reasonable in minds other than my own. > Speaking of command-line options, "--version" and "--help" aren't > documented in a lot of command reference pages. Is there a good > reason why? I am not aware of one. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > --help and --version are the standard options that are supported > everywhere. In the era before we had long options everywhere, we > implemented -V as an alternative in some programs, in particular those > in and around initdb, because of the version cross-checking it does > using those options. Ok, good to know. FWIW "-V" is almost universal among the client binaries (not just those "in and around initdb"). > At one point, long options where broken on some BSD versions. I don't > know what became of that, but if we don't have new information it might > be safest to leave things where they are. Can anyone confirm this? (If this actually affects any modern platforms it means that "--help" doesn't work at the very least, which seems a Bad Thing. So I'm a little skeptical that this is still a problem.) > Hence, the -V option is not the preferred public interface, so it's not > prominently documented, which may or may not be reasonable in minds > other than my own. Fair enough, but I think it's inconsistent to document it in some places but not in others. I think we ought to either declare "-V" deprecated (and perhaps remove the docs for it), or accept that we need to live with it because of long-options silliness and document "-V" as a valid alternate. -Neil
Neil Conway wrote:
> Peter Eisentraut wrote:
> > --help and --version are the standard options that are supported
> > everywhere. In the era before we had long options everywhere, we
> > implemented -V as an alternative in some programs, in particular those
> > in and around initdb, because of the version cross-checking it does
> > using those options.
>
> Ok, good to know. FWIW "-V" is almost universal among the client
> binaries (not just those "in and around initdb").
>
> > At one point, long options where broken on some BSD versions. I don't
> > know what became of that, but if we don't have new information it might
> > be safest to leave things where they are.
>
> Can anyone confirm this? (If this actually affects any modern platforms
> it means that "--help" doesn't work at the very least, which seems a Bad
> Thing. So I'm a little skeptical that this is still a problem.)
FreeBSD had a problem with double-dash args but I thought that related
to getopt, and I can't remember how that fits in. Maybe we defined '-'
in getopt and said it took an argument and tested for '-help' and
'-verbose', but now we just check argv right inside main. I can't
remember totally.
> > Hence, the -V option is not the preferred public interface, so it's not
> > prominently documented, which may or may not be reasonable in minds
> > other than my own.
>
> Fair enough, but I think it's inconsistent to document it in some places
> but not in others. I think we ought to either declare "-V" deprecated
> (and perhaps remove the docs for it), or accept that we need to live
> with it because of long-options silliness and document "-V" as a valid
> alternate.
Agreed. psql --help certainly looks inconsistent --- only --help and
--version are long.
---------------------------------------------------------------------------
Usage: psql [OPTIONS]... [DBNAME [USERNAME]]
General options: -d DBNAME specify database name to connect to (default:
"postgres") -c COMMAND run only single command (SQL or internal) and exit -f FILENAME execute commands from
file,then exit -l list available databases, then exit -v NAME=VALUE set psql variable NAME to VALUE -X
do not read startup file (~/.psqlrc) --help show this help, then exit --version output version
information,then exit
-- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610)
359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square,
Pennsylvania19073
On Wed, 2004-11-24 at 20:25 -0500, Bruce Momjian wrote: > FreeBSD had a problem with double-dash args but I thought that related > to getopt, and I can't remember how that fits in. Maybe we defined '-' > in getopt and said it took an argument and tested for '-help' and > '-verbose', but now we just check argv right inside main. I can't > remember totally. ISTM that port/getopt_long.c ought to allow long options to work even if the platform doesn't provide a getopt_long() itself. BTW, pg_dump's "-X ..." options seem weird. Why is the "-X" prefix necessary? ISTM pg_dump would be more consistent with standard command-line tools if we just provided the long options (such as --disable-triggers and so on) and did away with the "-X" prefixes. I'd like to propose these changes: (1) remove documentation for "-V", declare it deprecated. I don't see any reason to actually remove it, but this should at least make the current status quo more consistent. (2) add documentation for "--help" and "--version" flags, where appropriate (3) remove documentation for pg_dump's "-X ..." flags, just document the --long-option variant. Again, I don't see a need to remove support for the -X options, but we should declare them deprecated. Comments? > Agreed. psql --help certainly looks inconsistent --- only --help and > --version are long. Well, perhaps, but I don't think that's a problem (there is no reason that _every_ command-line flag needs to have both long and short options). -Neil