DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:from:date:message-id:subject:to
	:cc:content-type:content-transfer-encoding;
	b=dUaNhYzBN/Pk3Xaif9yAouikY2/Z3dc4zlDYo2tjF9DUSfPQ+Wl6OQY7W4X54tMj5a
	oJciAU8/2m9qxqDVmlCtXzSHqOt/Rvv6NUMrsSyCHSkU0pfrOhE77pZnfAHTd71kAzgm
	jcyPeX3YaxjCv9jJZ3jHNO5njzE5dvsJ707Is=
MIME-Version: 1.0
In-Reply-To: <3f0b79eb1002111757y3d11102n7fdfcee8f332f6d4@mail.gmail.com>
References: <bddc86151002101443t69d6e2e7rd6c76ea6287e6061@mail.gmail.com>
	<3f0b79eb1002111757y3d11102n7fdfcee8f332f6d4@mail.gmail.com>
From: Thom Brown <thombrown@gmail.com>
Date: Fri, 12 Feb 2010 16:15:03 +0000
Message-ID: <bddc86151002120815m5b9e6922p90aba868b5dae9d7@mail.gmail.com>
Subject: Re: Confusing link in streaming replication section
To: Fujii Masao <masao.fujii@gmail.com>
Cc: pgsql-docs@postgresql.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On 12 February 2010 01:57, Fujii Masao <masao.fujii@gmail.com> wrote:
> On Thu, Feb 11, 2010 at 7:43 AM, Thom Brown <thombrown@gmail.com> wrote:
>> I'm looking at the latest docs for PostgreSQL 9.0
>> (http://developer.postgresql.org/pgdocs/postgres/streaming-replication.h=
tml)
>> and under the description of primary_conninfo, there's a link to
>> section 30.1 (http://developer.postgresql.org/pgdocs/postgres/libpq-conn=
ect.html)
>> which is supposed to describe the string format. =A0Having looked at
>> that page, however, it's not crystal clear what is meant by this
>> string format. =A0One can only assume it's referring to the
>> PQconnectdbParams section and the keywords that can be used for it,
>> which would also apply to a connection string, but there's no mention
>> of a "format" on that page.
>
> Thanks for the report!
>
> Though at first PQconnectdb() had been linked by the SR doc, instead
> PQconnectdbParams() seems to have been linked wrongly when it was committ=
ed.
> How about changing the link so as to point to PQconnectdb() again? Or
> copy-pasting the following description from PQconnectdb() to the SR doc?
>
> -----------
> The passed string can be empty to use all default parameters, or it can
> contain one or more parameter settings separated by whitespace. Each
> parameter setting is in the form keyword =3D value. Spaces around the equ=
al
> sign are optional. To write an empty value, or a value containing spaces,
> surround it with single quotes, e.g., keyword =3D 'a value'. Single quote=
s
> and backslashes within the value must be escaped with a backslash,
> i.e., \' and \\.
>
> The currently recognized parameter key words are the same as above.
> -----------

Hmmm... well that last sentence refers to parameter key words which
won't appear on the SR page unless you copy and paste all that
information too.

I think the problem I have with there being a link to the libpq
control functions page is that the context of the settings isn't the
same, meaning the text on that page is specifically targetting people
looking for libpq info, rather than providing more generic information
which may be better placed in an appendix or something similar.

May I suggest a page on connection paramaters/connection strings which
can be referenced by multiple locations?  Otherwise I can imagine the
same information being presented a number of times throughout the
documentation.

Thanks

Thom