public inbox for [email protected]help / color / mirror / Atom feed
Add clarification example to EXEC SQL CONNECT with password 11+ messages / 3 participants [nested] [flat]
* Add clarification example to EXEC SQL CONNECT with password @ 2012-09-20 16:17 Alan B <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Alan B @ 2012-09-20 16:17 UTC (permalink / raw) To: pgsql-docs Hi list, Hope this is the right place to suggest that change in the docs, otherwise is there a ticket management system for this stuff somewhere? Paying attention to the documentation at http://www.postgresql.org/docs/8.4/static/ecpg-connect.html and subsequent versions of the page (I am using 8.4), there is the option to specify "user-name" in various ways. However this may be confused as a single parameter to the connect string while it is a combination of 1 or 2 parameters that cannot go into a single string. To avoid confusion I suggest providing a complete example in "Here are some examples of CONNECT statements:" as follows: EXEC SQL CONNECT TO [email protected]; EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john; EXEC SQL BEGIN DECLARE SECTION; const char *target = "[email protected]"; const char *user = "john"; const char *passwd = "secret"; EXEC SQL END DECLARE SECTION; ... EXEC SQL CONNECT TO :target USER :user USING :passwd; or EXEC SQL CONNECT TO :target USER :user/:passwd; To make the distinction of parameters and string variables evident. Alan ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 16:19 Bruce Momjian <[email protected]> parent: Alan B <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Bruce Momjian @ 2013-01-25 16:19 UTC (permalink / raw) To: Alan B <[email protected]>; +Cc: pgsql-docs On Thu, Sep 20, 2012 at 06:17:15PM +0200, Alan B wrote: > Hi list, > Hope this is the right place to suggest that change in the docs, otherwise is > there a ticket management system for this stuff somewhere? > > Paying attention to the documentation at http://www.postgresql.org/docs/8.4/ > static/ecpg-connect.html and subsequent versions of the page (I am using 8.4), > there is the option to specify "user-name" in various ways. However this may be > confused as a single parameter to the connect string while it is a combination > of 1 or 2 parameters that cannot go into a single string. > > To avoid confusion I suggest providing a complete example in "Here are some > examples of CONNECT statements:" as follows: > > > EXEC SQL CONNECT TO [email protected]; > > EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john; > > EXEC SQL BEGIN DECLARE SECTION; > const char *target = "[email protected]"; > const char *user = "john"; > const char *passwd = "secret"; > EXEC SQL END DECLARE SECTION; > ... > > EXEC SQL CONNECT TO :target USER :user USING :passwd; > or > EXEC SQL CONNECT TO :target USER :user/:passwd; > > To make the distinction of parameters and string variables evident. I had a look at this just now, and you are right that it is very confusing. I couldn't even figure out how to explain it in text, and agree that your example is the best solution. Attached patch applied to git head and 9.2. Thanks. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs Attachments: [text/x-diff] ecpg.diff (1.0K, 2-ecpg.diff) download | inline diff: diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml new file mode 100644 index 63aaf89..bf01857 *** a/doc/src/sgml/ecpg.sgml --- b/doc/src/sgml/ecpg.sgml *************** EXEC SQL CONNECT TO unix:postgresql://sq *** 194,202 **** EXEC SQL BEGIN DECLARE SECTION; const char *target = "[email protected]"; const char *user = "john"; EXEC SQL END DECLARE SECTION; ... ! EXEC SQL CONNECT TO :target USER :user; </programlisting> The last form makes use of the variant referred to above as character variable reference. You will see in later sections how C --- 194,205 ---- EXEC SQL BEGIN DECLARE SECTION; const char *target = "[email protected]"; const char *user = "john"; + const char *passwd = "secret"; EXEC SQL END DECLARE SECTION; ... ! 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 17:25 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Tom Lane @ 2013-01-25 17:25 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs Bruce Momjian <[email protected]> writes: > *** a/doc/src/sgml/ecpg.sgml > --- b/doc/src/sgml/ecpg.sgml > *************** EXEC SQL CONNECT TO unix:postgresql://sq > *** 194,202 **** > EXEC SQL BEGIN DECLARE SECTION; > const char *target = "[email protected]"; > const char *user = "john"; > EXEC SQL END DECLARE SECTION; > ... > ! EXEC SQL CONNECT TO :target USER :user; > </programlisting> > The last form makes use of the variant referred to above as > character variable reference. You will see in later sections how C > --- 194,205 ---- > EXEC SQL BEGIN DECLARE SECTION; > const char *target = "[email protected]"; > const char *user = "john"; > + const char *passwd = "secret"; > EXEC SQL END DECLARE SECTION; > ... > ! 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 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? regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 17:29 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Bruce Momjian @ 2013-01-25 17:29 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs On Fri, Jan 25, 2013 at 12:25:32PM -0500, Tom Lane wrote: > Bruce Momjian <[email protected]> writes: > > *** a/doc/src/sgml/ecpg.sgml > > --- b/doc/src/sgml/ecpg.sgml > > *************** EXEC SQL CONNECT TO unix:postgresql://sq > > *** 194,202 **** > > EXEC SQL BEGIN DECLARE SECTION; > > const char *target = "[email protected]"; > > const char *user = "john"; > > EXEC SQL END DECLARE SECTION; > > ... > > ! EXEC SQL CONNECT TO :target USER :user; > > </programlisting> > > The last form makes use of the variant referred to above as > > character variable reference. You will see in later sections how C > > --- 194,205 ---- > > EXEC SQL BEGIN DECLARE SECTION; > > const char *target = "[email protected]"; > > const char *user = "john"; > > + const char *passwd = "secret"; > > EXEC SQL END DECLARE SECTION; > > ... > > ! 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 > > 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. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 17:50 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Tom Lane @ 2013-01-25 17:50 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 18:19 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Bruce Momjian @ 2013-01-25 18:19 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote: > 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. OK, how is this? The C comment allows me to add 'or'. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs Attachments: [text/x-diff] ecpg2.diff (800B, 2-ecpg2.diff) download | inline 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 18:41 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Tom Lane @ 2013-01-25 18:41 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs Bruce Momjian <[email protected]> writes: > On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote: >> (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. > OK, how is this? The C comment allows me to add 'or'. It's still completely failing to address the problem that it's formatted as a fourth, independent example. Please remove the blank line. regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 18:43 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Bruce Momjian @ 2013-01-25 18:43 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote: > Bruce Momjian <[email protected]> writes: > > On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote: > >> (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. > > > OK, how is this? The C comment allows me to add 'or'. > > It's still completely failing to address the problem that it's formatted > as a fourth, independent example. Please remove the blank line. How is this? -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs Attachments: [text/x-diff] ecpg3.diff (862B, 2-ecpg3.diff) download | inline diff: diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml new file mode 100644 index bf01857..4d904cd *** a/doc/src/sgml/ecpg.sgml --- b/doc/src/sgml/ecpg.sgml *************** const char *passwd = "secret"; *** 198,205 **** EXEC SQL END DECLARE SECTION; ... 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 --- 198,204 ---- EXEC SQL END DECLARE SECTION; ... 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 18:43 Tom Lane <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Tom Lane @ 2013-01-25 18:43 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs Bruce Momjian <[email protected]> writes: > On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote: >> It's still completely failing to address the problem that it's formatted >> as a fourth, independent example. Please remove the blank line. > How is this? Yeah, that seems to work --- it looks like a single example now. regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2013-01-25 18:46 Bruce Momjian <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Bruce Momjian @ 2013-01-25 18:46 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Alan B <[email protected]>; pgsql-docs On Fri, Jan 25, 2013 at 01:43:59PM -0500, Tom Lane wrote: > Bruce Momjian <[email protected]> writes: > > On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote: > >> It's still completely failing to address the problem that it's formatted > >> as a fourth, independent example. Please remove the blank line. > > > How is this? > > Yeah, that seems to work --- it looks like a single example now. Thanks, done. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Add clarification example to EXEC SQL CONNECT with password @ 2014-01-20 11:50 Alan B <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 0 replies; 11+ messages in thread From: Alan B @ 2014-01-20 11:50 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs Hi Bruce, Tom, Great to see this addressed, thanks. Alan On Fri, Jan 25, 2013 at 7:46 PM, Bruce Momjian <[email protected]> wrote: > On Fri, Jan 25, 2013 at 01:43:59PM -0500, Tom Lane wrote: > > Bruce Momjian <[email protected]> writes: > > > On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote: > > >> It's still completely failing to address the problem that it's > formatted > > >> as a fourth, independent example. Please remove the blank line. > > > > > How is this? > > > > Yeah, that seems to work --- it looks like a single example now. > > Thanks, done. > > -- > Bruce Momjian <[email protected]> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + It's impossible for everything to be true. + > ^ permalink raw reply [nested|flat] 11+ messages in thread
end of thread, other threads:[~2014-01-20 11:50 UTC | newest] Thread overview: 11+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2012-09-20 16:17 Add clarification example to EXEC SQL CONNECT with password Alan B <[email protected]> 2013-01-25 16:19 ` Bruce Momjian <[email protected]> 2013-01-25 17:25 ` Tom Lane <[email protected]> 2013-01-25 17:29 ` Bruce Momjian <[email protected]> 2013-01-25 17:50 ` Tom Lane <[email protected]> 2013-01-25 18:19 ` Bruce Momjian <[email protected]> 2013-01-25 18:41 ` Tom Lane <[email protected]> 2013-01-25 18:43 ` Bruce Momjian <[email protected]> 2013-01-25 18:43 ` Tom Lane <[email protected]> 2013-01-25 18:46 ` Bruce Momjian <[email protected]> 2014-01-20 11:50 ` Alan B <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox