Re: Improve initdb and pg_controldata manual pages

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

-D directory
--pgdata=directory

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:

-D directory
--pgdata directory

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

OK.

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
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +