Bruce Momjian <bruce@momjian.us> 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