Lack of docs for libpq C Library

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. +

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.

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. +

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

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. +

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

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. +

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/

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

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

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. +

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. +

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

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. +

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/

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. +

-----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-----

"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

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. +