Skip site navigation (1) Skip section navigation (2)

Re: Improve initdb and pg_controldata manual pages

From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: PostgreSQL-documentation <pgsql-docs(at)postgresql(dot)org>
Subject: Re: Improve initdb and pg_controldata manual pages
Date: 2011-03-09 15:51:32
Message-ID: 201103091551.p29FpW126215@momjian.us (view raw or flat)
Thread:
Lists: pgsql-docs
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. +

In response to

Responses

pgsql-docs by date

Next:From: Tom LaneDate: 2011-03-09 15:57:48
Subject: Re: Improve initdb and pg_controldata manual pages
Previous:From: Peter EisentrautDate: 2011-03-09 15:44:03
Subject: Re: use of '=' in long options documentation

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group