Re: Improve initdb and pg_controldata manual pages

Tom Lane wrote:
> 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.

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

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