-V, --version -- deprecated?

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, Pennsylvania 19073

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