Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)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
> 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.
Well, looking at the detailed option list, it looks fine:
It is only at the top where we see the problem because -D/--pgdata is a
required argument and there are necesary spaces because we are showing
both -D and --pgdata followed by a single argument. The original patch
creator added '=' to be consistent with the syntax used below.
The bottom line is that there are many doc cases where this is used:
(no '='), so we should decide what we want in the docs.
We could do:
initdb [option...] -D directory
initdb [option...] --pgdata=directory
but showing two lines just to show short and long options seems silly
because they do the same thing.
I think we can use '=' in the detail option docs and not use '=' in the
summary at the top, but we should decide on a consistent approach, which
we don't have now.
> > 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.
Does professionally produced documentation have as many inconsistencies?
It seems one turns up everytime I go to change the docs.
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
+ It's impossible for everything to be true. +
In response to
pgsql-docs by date
|Next:||From: Tom Lane||Date: 2011-03-09 15:57:48|
|Subject: Re: Improve initdb and pg_controldata manual pages |
|Previous:||From: Peter Eisentraut||Date: 2011-03-09 15:44:03|
|Subject: Re: use of '=' in long options documentation|