Thread: Lack of docs for libpq C Library

Lack of docs for libpq C Library

From
Pavel Golub
Date:
Hello, pgsql-docs.

I noticed that some exported functions are not documented in the
Chapter 30. However, there are some info about them in other chapters,
e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
Character Set Conversion Between Server and Client".

This is the list of exported functions without docs:
================
PQclientEncoding
PQsetClientEncoding
PQconninfoFree
PQdsplen
PQenv2encoding
PQinitSSL
PQmblen
PQregisterThreadLock
appendPQExpBuffer
appendPQExpBufferChar
appendPQExpBufferStr
createPQExpBuffer
destroyPQExpBuffer
enlargePQExpBuffer
initPQExpBuffer
appendBinaryPQExpBuffer
pg_char_to_encoding
pg_encoding_to_char
pg_utf_mblen
pg_valid_server_encoding
pgresStatus
pqsignal
printfPQExpBuffer
resetPQExpBuffer
termPQExpBuffer

For me as a developer this is extremely important info.

Thanks for understanding.

--
With best wishes,
 Pavel                          mailto:pavel@gf.microolap.com


Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Pavel Golub wrote:
> Hello, pgsql-docs.
>
> I noticed that some exported functions are not documented in the
> Chapter 30. However, there are some info about them in other chapters,
> e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
> Character Set Conversion Between Server and Client".

Though they are exported, the are more for internal use, e.g. psql,
rather than something we want people using --- they can change from
release to release.

---------------------------------------------------------------------------


>
> This is the list of exported functions without docs:
> ================
> PQclientEncoding
> PQsetClientEncoding
> PQconninfoFree
> PQdsplen
> PQenv2encoding
> PQinitSSL
> PQmblen
> PQregisterThreadLock
> appendPQExpBuffer
> appendPQExpBufferChar
> appendPQExpBufferStr
> createPQExpBuffer
> destroyPQExpBuffer
> enlargePQExpBuffer
> initPQExpBuffer
> appendBinaryPQExpBuffer
> pg_char_to_encoding
> pg_encoding_to_char
> pg_utf_mblen
> pg_valid_server_encoding
> pgresStatus
> pqsignal
> printfPQExpBuffer
> resetPQExpBuffer
> termPQExpBuffer
>
> For me as a developer this is extremely important info.
>
> Thanks for understanding.
>
> --
> With best wishes,
>  Pavel                          mailto:pavel@gf.microolap.com
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
>
>                http://archives.postgresql.org

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Alvaro Herrera
Date:
Bruce Momjian wrote:
> Pavel Golub wrote:
> > Hello, pgsql-docs.
> >
> > I noticed that some exported functions are not documented in the
> > Chapter 30. However, there are some info about them in other chapters,
> > e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
> > Character Set Conversion Between Server and Client".
>
> Though they are exported, the are more for internal use, e.g. psql,
> rather than something we want people using --- they can change from
> release to release.

I disagree.  I think PQinitSSL is meant to be called from the
application, for example.  Same with PQsetClientEncoding.  And the
PQExpBuffer stuff is all very useful, and years ago when I wrote an app
to use it it annoyed me that there were no docs on it.  (Back then, I
didn't realize I could have complained about it or written the docs
myself).


> ---------------------------------------------------------------------------
>
>
> >
> > This is the list of exported functions without docs:
> > ================
> > PQclientEncoding
> > PQsetClientEncoding
> > PQconninfoFree
> > PQdsplen
> > PQenv2encoding
> > PQinitSSL
> > PQmblen
> > PQregisterThreadLock
> > appendPQExpBuffer
> > appendPQExpBufferChar
> > appendPQExpBufferStr
> > createPQExpBuffer
> > destroyPQExpBuffer
> > enlargePQExpBuffer
> > initPQExpBuffer
> > appendBinaryPQExpBuffer
> > pg_char_to_encoding
> > pg_encoding_to_char
> > pg_utf_mblen
> > pg_valid_server_encoding
> > pgresStatus
> > pqsignal
> > printfPQExpBuffer
> > resetPQExpBuffer
> > termPQExpBuffer


--
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Alvaro Herrera wrote:
> Bruce Momjian wrote:
> > Pavel Golub wrote:
> > > Hello, pgsql-docs.
> > >
> > > I noticed that some exported functions are not documented in the
> > > Chapter 30. However, there are some info about them in other chapters,
> > > e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
> > > Character Set Conversion Between Server and Client".
> >
> > Though they are exported, the are more for internal use, e.g. psql,
> > rather than something we want people using --- they can change from
> > release to release.
>
> I disagree.  I think PQinitSSL is meant to be called from the
> application, for example.  Same with PQsetClientEncoding.  And the

I see PQinitSSL and PQsetClientEncoding mentioned in the documentation;
is it lacking enough detail?

> PQExpBuffer stuff is all very useful, and years ago when I wrote an app
> to use it it annoyed me that there were no docs on it.  (Back then, I
> didn't realize I could have complained about it or written the docs
> myself).

True but we don't guarantee the API of many of these functions like we
do the documented ones.

---------------------------------------------------------------------------


>
>
> > ---------------------------------------------------------------------------
> >
> >
> > >
> > > This is the list of exported functions without docs:
> > > ================
> > > PQclientEncoding
> > > PQsetClientEncoding
> > > PQconninfoFree
> > > PQdsplen
> > > PQenv2encoding
> > > PQinitSSL
> > > PQmblen
> > > PQregisterThreadLock
> > > appendPQExpBuffer
> > > appendPQExpBufferChar
> > > appendPQExpBufferStr
> > > createPQExpBuffer
> > > destroyPQExpBuffer
> > > enlargePQExpBuffer
> > > initPQExpBuffer
> > > appendBinaryPQExpBuffer
> > > pg_char_to_encoding
> > > pg_encoding_to_char
> > > pg_utf_mblen
> > > pg_valid_server_encoding
> > > pgresStatus
> > > pqsignal
> > > printfPQExpBuffer
> > > resetPQExpBuffer
> > > termPQExpBuffer
>
>
> --
> Alvaro Herrera                                http://www.CommandPrompt.com/
> The PostgreSQL Company - Command Prompt, Inc.
>
> ---------------------------(end of broadcast)---------------------------
> TIP 9: In versions below 8.0, the planner will ignore your desire to
>        choose an index scan if your joining column's datatypes do not
>        match

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Tom Lane
Date:
Alvaro Herrera <alvherre@commandprompt.com> writes:
> I disagree.  I think PQinitSSL is meant to be called from the
> application, for example.  Same with PQsetClientEncoding.  And the
> PQExpBuffer stuff is all very useful, and years ago when I wrote an app
> to use it it annoyed me that there were no docs on it.  (Back then, I
> didn't realize I could have complained about it or written the docs
> myself).

PQinitSSL *is* documented, though looking at the para immediately raises
the question what the heck we are doing pointing to a random hp.com page
for SSL documentation.

PQsetClientEncoding seems to be documented in the wrong place.

As for the expbuffer stuff, that is intentionally not considered part of
libpq's exported API.  If someone uses it, they get to keep both parts
when it breaks.

            regards, tom lane

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> Alvaro Herrera <alvherre@commandprompt.com> writes:
> > I disagree.  I think PQinitSSL is meant to be called from the
> > application, for example.  Same with PQsetClientEncoding.  And the
> > PQExpBuffer stuff is all very useful, and years ago when I wrote an app
> > to use it it annoyed me that there were no docs on it.  (Back then, I
> > didn't realize I could have complained about it or written the docs
> > myself).
>
> PQinitSSL *is* documented, though looking at the para immediately raises
> the question what the heck we are doing pointing to a random hp.com page
> for SSL documentation.

I added that for 8.3.  The HP documentation seemed excellent, which is
why I added it.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Tom Lane
Date:
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> PQinitSSL *is* documented, though looking at the para immediately raises
>> the question what the heck we are doing pointing to a random hp.com page
>> for SSL documentation.

> I added that for 8.3.  The HP documentation seemed excellent, which is
> why I added it.

The question is not about whether that doc is good, bad, or indifferent;
it is about the likely lifespan of the URL.  A URL containing mostly
random numbers instead of words does not fill me with confidence.
Furthermore HP is hardly the authoritative reference on SSL.  Can't
we find an RFC or something?

            regards, tom lane

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Tom Lane wrote:
> >> PQinitSSL *is* documented, though looking at the para immediately raises
> >> the question what the heck we are doing pointing to a random hp.com page
> >> for SSL documentation.
>
> > I added that for 8.3.  The HP documentation seemed excellent, which is
> > why I added it.
>
> The question is not about whether that doc is good, bad, or indifferent;
> it is about the likely lifespan of the URL.  A URL containing mostly
> random numbers instead of words does not fill me with confidence.

True, and Magnus was concerned about that as well.  What I liked about
it was the diagrams which I haven't seen anywhere else.  Our doc
reference is:

    (See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html  for
    diagrams showing SSL certificate usage.)

I put it in parentheses to highlight the URL is only for reference to
the diagrams and explaination.  We can either remove the URL or remove
it if the URL changes.

SSL is pretty complicated so when I saw something that made it clearer,
I added it.

> Furthermore HP is hardly the authoritative reference on SSL.  Can't
> we find an RFC or something?

See above.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Peter Eisentraut
Date:
Am Donnerstag, 31. Januar 2008 schrieb Bruce Momjian:
> I put it in parentheses to highlight the URL is only for reference to
> the diagrams and explaination.  We can either remove the URL or remove
> it if the URL changes.
>
> SSL is pretty complicated so when I saw something that made it clearer,
> I added it.
>
> > Furthermore HP is hardly the authoritative reference on SSL.  Can't
> > we find an RFC or something?
>
> See above.

If anything, we should link to OpenSSL, because they implement the API we are
referring to.  I don't know what HP has to do with it.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Re: Lack of docs for libpq C Library

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
>>> Furthermore HP is hardly the authoritative reference on SSL.  Can't
>>> we find an RFC or something?
>>
>> See above.

> If anything, we should link to OpenSSL, because they implement the API we are
> referring to.  I don't know what HP has to do with it.

Yeah, I was thinking a simple pointer to www.openssl.org would be more
appropriate.  We're not here to substitute for somebody doing their
own Google search ...

            regards, tom lane

Re: Lack of docs for libpq C Library

From
Alvaro Herrera
Date:
Bruce Momjian wrote:

> True, and Magnus was concerned about that as well.  What I liked about
> it was the diagrams which I haven't seen anywhere else.  Our doc
> reference is:
>
>     (See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html  for
>     diagrams showing SSL certificate usage.)
>
> I put it in parentheses to highlight the URL is only for reference to
> the diagrams and explaination.  We can either remove the URL or remove
> it if the URL changes.

If you really like that page, you could link to archive.org's version of
it:

http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html

--
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Alvaro Herrera wrote:
> Bruce Momjian wrote:
>
> > True, and Magnus was concerned about that as well.  What I liked about
> > it was the diagrams which I haven't seen anywhere else.  Our doc
> > reference is:
> >
> >     (See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html  for
> >     diagrams showing SSL certificate usage.)
> >
> > I put it in parentheses to highlight the URL is only for reference to
> > the diagrams and explaination.  We can either remove the URL or remove
> > it if the URL changes.
>
> If you really like that page, you could link to archive.org's version of
> it:
>
> http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html
                             --------
                             2006-09-03

Well, archive.org indicates the URL has been stable for at least 15
months so the original might be OK.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Alvaro Herrera wrote:
> Bruce Momjian wrote:
>
> > True, and Magnus was concerned about that as well.  What I liked about
> > it was the diagrams which I haven't seen anywhere else.  Our doc
> > reference is:
> >
> >     (See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html  for
> >     diagrams showing SSL certificate usage.)
> >
> > I put it in parentheses to highlight the URL is only for reference to
> > the diagrams and explaination.  We can either remove the URL or remove
> > it if the URL changes.
>
> If you really like that page, you could link to archive.org's version of
> it:
>
> http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html

Basically, given the URL has been unchanged since at least September
2006 and because it is hard to find via Google, I think we should keep
the HP URL (to give them credit) and fall back to archive.org in case
the URL ever becomes inactive.

SSL is not an easy thing to underestand so having links to good
documentation is a big plus for us.  Using that documentation I was able
to understand SSL enough to make some improvements to the SSL code that
I will apply for 8.4.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
> >>> Furthermore HP is hardly the authoritative reference on SSL.  Can't
> >>> we find an RFC or something?
> >>
> >> See above.
>
> > If anything, we should link to OpenSSL, because they implement the API we are
> > referring to.  I don't know what HP has to do with it.
>
> Yeah, I was thinking a simple pointer to www.openssl.org would be more

I looked at the SSL docs and they are _minimal_:

    http://www.openssl.org/docs/

In fact "[STILL INCOMPLETE]" is on almost every item.

> appropriate.  We're not here to substitute for somebody doing their
> own Google search ...

The HP page is not a primary Google hit --- it took me trolling though
many copies of the SSL manual pages to find it.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Alvaro Herrera
Date:
Bruce Momjian wrote:
> Alvaro Herrera wrote:

> > If you really like that page, you could link to archive.org's version of
> > it:
> >
> > http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html
>                              --------
>                              2006-09-03
>
> Well, archive.org indicates the URL has been stable for at least 15
> months so the original might be OK.

The point is that archive.org will keep that copy online even if hp.com
decides to shut it down or change it.

--
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Re: Lack of docs for libpq C Library

From
Peter Eisentraut
Date:
Bruce Momjian wrote:
> I looked at the SSL docs and they are _minimal_:
>
>     http://www.openssl.org/docs/
>
> In fact "[STILL INCOMPLETE]" is on almost every item.
>
> > appropriate.  We're not here to substitute for somebody doing their
> > own Google search ...
>
> The HP page is not a primary Google hit --- it took me trolling though
> many copies of the SSL manual pages to find it.

Nevertheless, I think making such semantically significant changes *hours*
before a major release should be avoided.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Peter Eisentraut wrote:
> Bruce Momjian wrote:
> > I looked at the SSL docs and they are _minimal_:
> >
> >     http://www.openssl.org/docs/
> >
> > In fact "[STILL INCOMPLETE]" is on almost every item.
> >
> > > appropriate.  We're not here to substitute for somebody doing their
> > > own Google search ...
> >
> > The HP page is not a primary Google hit --- it took me trolling though
> > many copies of the SSL manual pages to find it.
>
> Nevertheless, I think making such semantically significant changes *hours*
> before a major release should be avoided.

Well, it is just SGML --- I don't see a problem with adjustments at this
time.  FYI, the HP URL was placed there at least a month ago by me.  I
did add a comment in the SGML based on Alvaro's suggestion.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
"Joshua D. Drake"
Date:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Thu, 31 Jan 2008 20:18:27 -0300
Alvaro Herrera <alvherre@commandprompt.com> wrote:

> Bruce Momjian wrote:
> > Alvaro Herrera wrote:
> 
> > > If you really like that page, you could link to archive.org's
> > > version of it:
> > > 
> > > http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html
> >                              --------
> >                              2006-09-03
> > 
> > Well, archive.org indicates the URL has been stable for at least 15
> > months so the original might be OK.
> 
> The point is that archive.org will keep that copy online even if
> hp.com decides to shut it down or change it.
> 

There is a question to the legality of the archive.org copy. The legal
notice of the document states that there must be a valid license for
the product to copy. 

*IF* we link that document, we need to link to the HP site.

Sincerely,

Joshua D. Drake

- -- 
The PostgreSQL Company since 1997: http://www.commandprompt.com/ 
PostgreSQL Community Conference: http://www.postgresqlconference.org/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
PostgreSQL SPI Liaison | SPI Director |  PostgreSQL political pundit

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHopXjATb/zqfZUUQRAsrjAJ9mbLhVY1w2vKmiG7y3FLpf/p2zUQCffrwY
3OIVlDrmxPSbGxaColBgQ2Y=
=G3XM
-----END PGP SIGNATURE-----

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> "Joshua D. Drake" <jd@commandprompt.com> writes:
> > Alvaro Herrera <alvherre@commandprompt.com> wrote:
> >> The point is that archive.org will keep that copy online even if
> >> hp.com decides to shut it down or change it.
>
> > There is a question to the legality of the archive.org copy. The legal
> > notice of the document states that there must be a valid license for
> > the product to copy.
>
> > *IF* we link that document, we need to link to the HP site.
>
> Uh, this is nonsense.  Even if archive.org is violating HP's copyright
> (a point un-tested at law), we cannot be violating anything by which
> URL we choose to point to.

Right, it seems like it would be archive.org's problem.

> The main problem with using the link as it stands is that it is *highly*
> unlikely that it will remain valid for the lifespan of the PG 8.3
> documentation (let alone subsequent versions).  I've been dealing with

Did you see Alvaro's archive.org URL that showed it was the same in
September, 2006?

> HP's website for many years and I have good reason to know that page
> URLs of the kind that Bruce has chosen to quote do not have long shelf
> lives.
>
> Personally I would vote for not having the link there at all.  It is not
> adding anything very critical to our docs, it is likely to be broken
> soon (for some value of soon), and if there is any question about the
> legality then that's just frosting on the cake.

I found it useful and I think others will as well.  Agreed it is not
critical, but does a URL have to be critical to be on our docs.

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
Tom Lane
Date:
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> The main problem with using the link as it stands is that it is *highly*
>> unlikely that it will remain valid for the lifespan of the PG 8.3
>> documentation (let alone subsequent versions).  I've been dealing with

> Did you see Alvaro's archive.org URL that showed it was the same in
> September, 2006?

Yeah, which means its half-life is about gone, in my experience.

            regards, tom lane

Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Tom Lane wrote:
> >> The main problem with using the link as it stands is that it is *highly*
> >> unlikely that it will remain valid for the lifespan of the PG 8.3
> >> documentation (let alone subsequent versions).  I've been dealing with
>
> > Did you see Alvaro's archive.org URL that showed it was the same in
> > September, 2006?
>
> Yeah, which means its half-life is about gone, in my experience.

OK, you used to work for HP so you certainly know more than I do.
Should I use archive.org instead?

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

  + If your life is a hard drive, Christ can be your backup. +

Re: Lack of docs for libpq C Library

From
"Joshua D. Drake"
Date:
Tom Lane wrote:
> "Joshua D. Drake" <jd@commandprompt.com> writes:
>> Alvaro Herrera <alvherre@commandprompt.com> wrote:
>>> The point is that archive.org will keep that copy online even if
>>> hp.com decides to shut it down or change it.
>
>> There is a question to the legality of the archive.org copy. The legal
>> notice of the document states that there must be a valid license for
>> the product to copy.
>
>> *IF* we link that document, we need to link to the HP site.
>
> Uh, this is nonsense.  Even if archive.org is violating HP's copyright
> (a point un-tested at law), we cannot be violating anything by which
> URL we choose to point to.

I think you missed my point :). My point was if HP got snarky about it,
the link would die. Whereas it is likely that HP would keep their link
up (in theory of course).

>
> The main problem with using the link as it stands is that it is *highly*
> unlikely that it will remain valid for the lifespan of the PG 8.3
> documentation (let alone subsequent versions).  I've been dealing with
> HP's website for many years and I have good reason to know that page
> URLs of the kind that Bruce has chosen to quote do not have long shelf
> lives.

Not arguing with this. I just think if we are going to link it, we
should link the authoritative source.

>
> Personally I would vote for not having the link there at all.  It is not
> adding anything very critical to our docs, it is likely to be broken
> soon (for some value of soon), and if there is any question about the
> legality then that's just frosting on the cake.

It seems to me that if we are going to have the information we need to
have it from a source that is reasonably guaranteed to be maintained. If
we don't trust that HP will do that then I would agree that we should
leave the link out.

Sincerely,

Joshua D. Drake



Re: Lack of docs for libpq C Library

From
Tom Lane
Date:
"Joshua D. Drake" <jd@commandprompt.com> writes:
> Alvaro Herrera <alvherre@commandprompt.com> wrote:
>> The point is that archive.org will keep that copy online even if
>> hp.com decides to shut it down or change it.

> There is a question to the legality of the archive.org copy. The legal
> notice of the document states that there must be a valid license for
> the product to copy.

> *IF* we link that document, we need to link to the HP site.

Uh, this is nonsense.  Even if archive.org is violating HP's copyright
(a point un-tested at law), we cannot be violating anything by which
URL we choose to point to.

The main problem with using the link as it stands is that it is *highly*
unlikely that it will remain valid for the lifespan of the PG 8.3
documentation (let alone subsequent versions).  I've been dealing with
HP's website for many years and I have good reason to know that page
URLs of the kind that Bruce has chosen to quote do not have long shelf
lives.

Personally I would vote for not having the link there at all.  It is not
adding anything very critical to our docs, it is likely to be broken
soon (for some value of soon), and if there is any question about the
legality then that's just frosting on the cake.

            regards, tom lane

Re: Lack of docs for libpq C Library

From
Pavel Golub
Date:
Hello, Bruce.

You wrote:

BM> Alvaro Herrera wrote:
>> Bruce Momjian wrote:
>> > Pavel Golub wrote:
>> > > Hello, pgsql-docs.
>> > >
>> > > I noticed that some exported functions are not documented in the
>> > > Chapter 30. However, there are some info about them in other chapters,
>> > > e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
>> > > Character Set Conversion Between Server and Client".
>> >
>> > Though they are exported, the are more for internal use, e.g. psql,
>> > rather than something we want people using --- they can change from
>> > release to release.
>>
>> I disagree.  I think PQinitSSL is meant to be called from the
>> application, for example.  Same with PQsetClientEncoding.  And the

BM> I see PQinitSSL and PQsetClientEncoding mentioned in the documentation;
BM> is it lacking enough detail?

Well they are. But in wrong place. I was using 'SET client_encoding TO
xxx' SQL a long time. And then I found PQsetClientEncoding in wrong
place.

Then PQmblen function. I beleive it means PQMultiByteLength? If so, it
would be very usefull for me.

>> PQExpBuffer stuff is all very useful, and years ago when I wrote an app
>> to use it it annoyed me that there were no docs on it.  (Back then, I
>> didn't realize I could have complained about it or written the docs
>> myself).

BM> True but we don't guarantee the API of many of these functions like we
BM> do the documented ones.

You may state in that these functions are internal and nobody is
recommended using them. At least developers haven't to try to guess
what they mean and create some kind of Colossus with feet of clay based on
these guesses.

BM> ---------------------------------------------------------------------------


>>
>>
>> > ---------------------------------------------------------------------------
>> >
>> >
>> > >
>> > > This is the list of exported functions without docs:
>> > > ================
>> > > PQclientEncoding
>> > > PQsetClientEncoding
>> > > PQconninfoFree
>> > > PQdsplen
>> > > PQenv2encoding
>> > > PQinitSSL
>> > > PQmblen
>> > > PQregisterThreadLock
>> > > appendPQExpBuffer
>> > > appendPQExpBufferChar
>> > > appendPQExpBufferStr
>> > > createPQExpBuffer
>> > > destroyPQExpBuffer
>> > > enlargePQExpBuffer
>> > > initPQExpBuffer
>> > > appendBinaryPQExpBuffer
>> > > pg_char_to_encoding
>> > > pg_encoding_to_char
>> > > pg_utf_mblen
>> > > pg_valid_server_encoding
>> > > pgresStatus
>> > > pqsignal
>> > > printfPQExpBuffer
>> > > resetPQExpBuffer
>> > > termPQExpBuffer
>>
>>
>> --
>> Alvaro Herrera                                http://www.CommandPrompt.com/
>> The PostgreSQL Company - Command Prompt, Inc.
>>
>> ---------------------------(end of broadcast)---------------------------
>> TIP 9: In versions below 8.0, the planner will ignore your desire to
>>        choose an index scan if your joining column's datatypes do not
>>        match




--
With best wishes,
 Pavel                          mailto:pavel@gf.microolap.com


Re: Lack of docs for libpq C Library

From
Bruce Momjian
Date:
Tom Lane wrote:
> Alvaro Herrera <alvherre@commandprompt.com> writes:
> > I disagree.  I think PQinitSSL is meant to be called from the
> > application, for example.  Same with PQsetClientEncoding.  And the
> > PQExpBuffer stuff is all very useful, and years ago when I wrote an app
> > to use it it annoyed me that there were no docs on it.  (Back then, I
> > didn't realize I could have complained about it or written the docs
> > myself).
>
> PQsetClientEncoding seems to be documented in the wrong place.

I have moved the libpq client encoding documentation into the libpq doc
section, and just referenced it from the localization docs.  Backpatched
to 8.3.X.

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

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/charset.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v
retrieving revision 2.84
diff -c -c -r2.84 charset.sgml
*** doc/src/sgml/charset.sgml    28 Sep 2007 22:25:49 -0000    2.84
--- doc/src/sgml/charset.sgml    6 Mar 2008 15:32:28 -0000
***************
*** 1110,1140 ****

        <listitem>
         <para>
!         Using <application>libpq</> functions.
!         <command>\encoding</command> actually calls
!         <function>PQsetClientEncoding()</function> for its purpose.
!
! <synopsis>
! int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
! </synopsis>
!
!         where <replaceable>conn</replaceable> is a connection to the server,
!         and <replaceable>encoding</replaceable> is the encoding you
!         want to use. If the function successfully sets the encoding, it returns 0,
!         otherwise -1. The current encoding for this connection can be determined by
!         using:
!
! <synopsis>
! int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
! </synopsis>
!
!         Note that it returns the encoding ID, not a symbolic string
!         such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
!         can use:
!
! <synopsis>
! char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
! </synopsis>
         </para>
        </listitem>

--- 1110,1116 ----

        <listitem>
         <para>
!         <application>libpq</> (<xref linkend="libpq-control">) has functions to control the client encoding.
         </para>
        </listitem>

Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.255
diff -c -c -r1.255 libpq.sgml
*** doc/src/sgml/libpq.sgml    31 Jan 2008 23:31:33 -0000    1.255
--- doc/src/sgml/libpq.sgml    6 Mar 2008 15:32:32 -0000
***************
*** 4417,4422 ****
--- 4417,4472 ----
    <variablelist>
     <varlistentry>
      <term>
+      <function>PQclientEncoding</function>
+      <indexterm>
+       <primary>PQclientEncoding</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the client encoding.
+       <synopsis>
+       int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
+       </synopsis>
+
+       Note that it returns the encoding ID, not a symbolic string
+       such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
+       can use:
+
+ <synopsis>
+ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
+ </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
+      <function>PQsetClientEncoding</function>
+      <indexterm>
+       <primary>PQsetClientEncoding</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sets the client encoding.
+       <synopsis>
+       int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char
*<replaceable>encoding</replaceable>);
+       </synopsis>
+
+       <replaceable>conn</replaceable> is a connection to the server,
+       and <replaceable>encoding</replaceable> is the encoding you want to
+       use. If the function successfully sets the encoding, it returns 0,
+       otherwise -1. The current encoding for this connection can be
+       determined by using <function>PQclientEncoding</>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
       <function>PQsetErrorVerbosity</function>
       <indexterm>
        <primary>PQsetErrorVerbosity</primary>