public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: Bruce Momjian <[email protected]>
Cc: Alan B <[email protected]>
Cc: [email protected]
Subject: Re: Add clarification example to EXEC SQL CONNECT with password
Date: Fri, 25 Jan 2013 12:50:12 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <CAGbN=G6P1dy4Q03oKdQig_oUWj82W_x67MRMwX2J+9DrFc=cxw@mail.gmail.com>
	<[email protected]>
	<[email protected]>
	<[email protected]>
List-Unsubscribe: <mailto:[email protected]?body=unsub%20pgsql-docs>

Bruce Momjian <[email protected]> writes:
> On Fri, Jan 25, 2013 at 12:25:32PM -0500, Tom Lane wrote:
>>> ! EXEC SQL CONNECT TO :target USER :user USING :passwd;
>>> ! 
>>> ! EXEC SQL CONNECT TO :target USER :user/:passwd;

>> This sure looks like it has broken the intention of the paragraph
>> immediately after the example.  Also, it seems like you are providing
>> two alternative ways of doing the same thing, but not explaining that.
>> How is a reader supposed to know that he doesn't have to do both
>> commands?

> Yeah, I was worried about that, so I added the blank line.  If you look
> at the docs, we already are providing three connection examples, so now
> there are four.  You can see the current docs here (the official ones
> are not updated yet):
> 	http://momjian.us/pgsql_docs/ecpg-connect.html#ECPG-CONNECTING
> I am open to suggestions.

(looks at the whole section) As-is, it's definitely not good, because
before there were three independent examples, and now there are three
and a half --- the added example depends on the variables declared in
the third example.  But using the blank line means you've formatted it
as a stand-alone fourth example, which is not only wrong in itself but
it screws up the meanings of both of the subsequent paragraphs.

Perhaps changing that blank line to something like " /* or */" would
help?  Then it would look more like an alternative within the same
example, which would also help with making the following two paras
still be sensible.

			regards, tom lane


-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

view thread (11+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: Add clarification example to EXEC SQL CONNECT with password
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox