To: Bruce Momjian <bruce@momjian.us>
cc: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Subject: Re: Improve initdb and pg_controldata manual pages 
In-reply-to: <201103091454.p29EsHG03787@momjian.us> 
References: <201103091454.p29EsHG03787@momjian.us>
Comments: In-reply-to Bruce Momjian <bruce@momjian.us>
	message dated "Wed, 09 Mar 2011 09:54:16 -0500"
Date: Wed, 09 Mar 2011 10:16:43 -0500
Message-ID: <23885.1299683803@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> This seems like the most bizarre choice you could have made.
>> It now looks like the preferred spelling of initdb's switch,
>> for instance, is
>> 
>> initdb --pgdata= /path/name
>> 
>> ie, *both* an equal sign and a space.  Please rethink this.

> Well, it actually looks like this:

> 	initdb [option...] --pgdata= | -D directory 

> and this gets back to whether we are going to show '=' for long
> switches, which I am waiting on a reply about.

Yeah.  I had not had an opinion about that before, but if this is the
sort of context the equal signs are going to be used in, I think we'd
be better off omitting them.  There are two correct ways to use a
long form option with argument:

	--switch=value
	--switch value

This case *does not work*:

	--switch= value

(At least on my machine, the switch is presumed to have an empty-string
value and then the value is seen as the next command line item.)
So we have to stay far away from any documentation layout that even
hints that that's the way to do it.

> Also, keep in mind that the --help output often shows '=', e.g. from
> pg_dump:

Right.  I think we should leave those alone, though, if only because
changing them will cause a lot of pain for translators and it's not
worth it.  The syntax shown in those messages is correct, it's just not
the whole truth.  The SGML documentation is telling a different subset
of the truth, and I'm OK with that too.  Since "the truth" about what
you can say does vary for different people depending on the local getopt
library, I can't get too excited about trying to document every case
that might possibly work.

			regards, tom lane