more adequate usage msg: pg_controldata.diff

A better one, slightly enhancing error reporting.

----- Original Message -----
From: "Serguei Mokhov" <mokhov@cs.concordia.ca>
Sent: January 02, 2003 3:41 AM

DATADIR is not an option. What needs to be done is that the "Usage:"
synopsis comes before the textual explanation, so you can write

Usage:
pg_controldata DATADIR

pg_controldata does something with DATADIR.

Options:
--...

We should do this consistently with all tools, though.

Serguei Mokhov writes:

A better one, slightly enhancing error reporting.

----- Original Message -----
From: "Serguei Mokhov" <mokhov@cs.concordia.ca>
Sent: January 02, 2003 3:41 AM

Making pg_controldata's usage info more adequate.

-s

pg_controldata.diff

--
Peter Eisentraut peter_e@gmx.net

Patch applied, with slight adjustment. New output is:

#$ pg_controldata --help
Usage:
pg_controldata [OPTION]

Options:
DATADIR show cluster control information for DATADIR
-?, --help display this help and exit
-V, --version display pg_controldata's version and exit

pg_controldata displays PostgreSQL database cluster control information.
If no data directory is specified, the environment variable PGDATA
is used.

Report bugs to <pgsql-bugs@postgresql.org>.

Also, DATADIR is optional.

---------------------------------------------------------------------------

Serguei Mokhov wrote:

A better one, slightly enhancing error reporting.

----- Original Message -----
From: "Serguei Mokhov" <mokhov@cs.concordia.ca>
Sent: January 02, 2003 3:41 AM

Making pg_controldata's usage info more adequate.

-s

pg_controldata.diff

[ Attachment, skipping... ]

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/users-lounge/docs/faq.html

-- 
  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

Peter Eisentraut wrote:

Bruce Momjian writes:

Patch applied, with slight adjustment. New output is:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in the
options list.)

I tried to subtely point out that it is optional. The C code is:

if (argc > 1)
DataDir = argv[1];
else
DataDir = getenv("PGDATA");
if (DataDir == NULL)
{
fprintf(stderr, _("%s: no data directory specified\n"), progname);
fprintf(stderr, _("Try '%s --help' for more information.\n"), progname);
exit(1);
}

and it does work without it:

$ pg_controldata
pg_control version number: 72
Catalog version number: 200212121
Database cluster state: in production
pg_control last modified: 01/09/03 07:34:11
Current log file ID: 0
Next log file segment: 3
Latest checkpoint location: 0/2294848
Prior checkpoint location: 0/8A9C60
Latest checkpoint's REDO location: 0/2294848
Latest checkpoint's UNDO location: 0/0
Latest checkpoint's StartUpID: 12
Latest checkpoint's NextXID: 6351
Latest checkpoint's NextOID: 156300
Time of latest checkpoint: 01/09/03 07:34:08
Database block size: 8192
Blocks per segment of large relation: 131072
Maximum length of identifiers: 64
Maximum number of function arguments: 32
Date/time type storage: Floating point
Maximum length of locale name: 128
LC_COLLATE: C
LC_CTYPE: C

-- 
  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

Bruce Momjian writes:

Patch applied, with slight adjustment. New output is:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in the
options list.)

--
Peter Eisentraut peter_e@gmx.net

Peter Eisentraut <peter_e@gmx.net> writes:

Bruce Momjian writes:

Patch applied, with slight adjustment. New output is:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in the
options list.)

Actually, it is optional for pg_controldata. The usage message is
technically correct as it stands because pg_controldata accepts at most
one argument (either --help, --version, or a DATADIR name).

At some point in the future we might alter the program so that it can
take some switches as well as a DATADIR name, and at that time the
distinction between switches and DATADIR would become significant.
But as of today, a usage message like
pg_controldata [options] [DATADIR]
would actually be wrong, so I'm not sure what to put instead.

I agree with Peter's objection in principle, but given that the program
has such a limited commandline syntax, I can't find a hard reason to do
otherwise than Bruce did.

regards, tom lane

Bruce Momjian writes:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in the
options list.)

I tried to subtely point out that it is optional.

But the help output is wrong. It lists DATADIR as an option, which it is
not. (An option is something like -a or --foo. The other things are
arguments.) See my message to Serguei about how to do it better.

--
Peter Eisentraut peter_e@gmx.net

[haven't been following the lists for quite some time]

Quoting Tom Lane <tgl@sss.pgh.pa.us>:

Actually, it is optional for pg_controldata. The usage message is
technically correct as it stands because pg_controldata accepts at most
one argument (either --help, --version, or a DATADIR name).

pg_controldata [ DATADIR | options ]

Will the above make more happy people?
Aren't there more serious issues to worry about? ;-)

-s

-------------------------------------------------
This mail sent through IMP: http://horde.org/imp/

Quoting Peter Eisentraut <peter_e@gmx.net>:

Bruce Momjian writes:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in

the

options list.)

I tried to subtely point out that it is optional.

But the help output is wrong. It lists DATADIR as an option, which it is
not. (An option is something like -a or --foo. The other things are
arguments.) See my message to Serguei about how to do it better.

[optional to comment on]: but aren't options are sort of command-line arguments
as well? ;-)

I don't mind either one of them, just as long as they are more or less
consistent with other tools and so that I can finally translate them :)

-s

-------------------------------------------------
This mail sent through IMP: http://horde.org/imp/

Peter Eisentraut wrote:

Bruce Momjian writes:

I explained in my last message that this patch is wrong. Please revert
it. (DATADIR is not an option and therefore it shouldn't be listed in the
options list.)

I tried to subtely point out that it is optional.

But the help output is wrong. It lists DATADIR as an option, which it is
not. (An option is something like -a or --foo. The other things are
arguments.) See my message to Serguei about how to do it better.

It is my understanding that -a and the like are _flags_. PGDATA is an
optional argument, or "option" for short. I don't see how having a dash
is required to make something an option. When I do:

cat [-t -v] [file ...]

I consider "file" to be an optional argument, or option. It of course
isn't a flag.

-- 
  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

Bruce Momjian writes:

It is my understanding that -a and the like are _flags_. PGDATA is an
optional argument, or "option" for short. I don't see how having a dash
is required to make something an option. When I do:

cat [-t -v] [file ...]

I consider "file" to be an optional argument, or option. It of course
isn't a flag.

I disagree. The things passed to the main() function are "arguments",
hence the names argc and argv. The things with the dashes are "options",
hence the name of the function getopt(). There are optional arguments,
there are optional options. Also, options can take arguments or not.

--
Peter Eisentraut peter_e@gmx.net