Date: Fri, 25 Jan 2013 13:19:21 -0500
From: Bruce Momjian <bruce@momjian.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Alan B <alan77codebits@gmail.com>, pgsql-docs@postgresql.org
Subject: Re: Add clarification example to EXEC SQL CONNECT with
 password
Message-ID: <20130125181921.GD6848@momjian.us>
References: 
 <CAGbN=G6P1dy4Q03oKdQig_oUWj82W_x67MRMwX2J+9DrFc=cxw@mail.gmail.com>
	<20130125161942.GA6848@momjian.us> <14376.1359134732@sss.pgh.pa.us>
	<20130125172959.GB6848@momjian.us> <14933.1359136212@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="Y5rl02BVI9TCfPar"
Content-Disposition: inline
In-Reply-To: <14933.1359136212@sss.pgh.pa.us>
User-Agent: Mutt/1.5.20 (2009-06-14)
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org


--Y5rl02BVI9TCfPar
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote:
> 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.

OK, how is this?  The C comment allows me to add 'or'.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

--Y5rl02BVI9TCfPar
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="ecpg2.diff"

diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
new file mode 100644
index bf01857..6326439
*** a/doc/src/sgml/ecpg.sgml
--- b/doc/src/sgml/ecpg.sgml
*************** EXEC SQL END DECLARE SECTION;
*** 199,205 ****
   ...
  EXEC SQL CONNECT TO :target USER :user USING :passwd;
  
! EXEC SQL CONNECT TO :target USER :user/:passwd;
  </programlisting>
     The last form makes use of the variant referred to above as
     character variable reference.  You will see in later sections how C
--- 199,205 ----
   ...
  EXEC SQL CONNECT TO :target USER :user USING :passwd;
  
! /* or EXEC SQL CONNECT TO :target USER :user/:passwd; */
  </programlisting>
     The last form makes use of the variant referred to above as
     character variable reference.  You will see in later sections how C

--Y5rl02BVI9TCfPar
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0


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

--Y5rl02BVI9TCfPar--