Re: [DOCS] [GENERAL] Gripe: bytea_output default => data corruption
ljb wrote: > [email protected] wrote: > > I think we should simply remove the description of *how* the escaping is > > performed, and state only that the function produces a suitably escaped > > literal string. Anything else is not future-proof, and could someday > > break the way this wording did. > > Perhaps it would be best to remove escaping details here. But the > description of PQescapeBytea() might need to be rewritten, too. Without > describing exactly what PQescapeByteaConn() does, it is hard to understand > what PQescapeBytea() does not do, and why it therefore "might give the > wrong results". > > I think the actual function behavior should be documented somewhere. Even > though it might change again. Based on this report, I have created the attached documentation patch which clarifies the libpq behavior for escaping bytea. I am planning to backpatch this to 9.0 as well. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7b70970..26f5140 100644 *** a/doc/src/sgml/libpq.sgml --- b/doc/src/sgml/libpq.sgml *** unsigned char *PQescapeByteaConn(PGconn *** 3419,3434 !Certain byte values must be escaped (but all !byte values can be escaped) when used as part !of a bytea literal in an SQL !statement. In general, to escape a byte, it is converted into the !three digit octal number equal to the octet value, and preceded by !usually two backslashes. The single quote (') and backslash !(\) characters have special alternative escape !sequences. See for more !information. PQescapeByteaConn performs this !operation, escaping only the minimally required bytes. --- 3419,3429 !Certain byte values must be escaped when used as part of a !bytea literal in an SQL statement. !PQescapeByteaConn escapes such bytes using !either hex encoding or backslash escaping. See for more information. *** unsigned char *PQescapeBytea(const unsig *** 3486,3495 The only difference from PQescapeByteaConn is that PQescapeBytea does not take a PGconn parameter. Because of this, it cannot adjust its behavior !depending on the connection properties (in particular, whether !standard-conforming strings are enabled) and therefore !it might give the wrong results. Also, it has no !way to return an error message on failure. --- 3481,3490 The only difference from PQescapeByteaConn is that PQescapeBytea does not take a PGconn parameter. Because of this, it cannot adjust its behavior !depending on the connection properties (e.g. !standard_conforming_strings, bytea_output) !and therefore might give the wrong results. Also, !it has no way to return an error message on failure. diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml index 2288f1b..c43f142 100644 *** a/doc/src/sgml/release-9.0.sgml --- b/doc/src/sgml/release-9.0.sgml *** *** 2342,2348 whether hex or traditional format is used for bytea output. Libpq's PQescapeByteaConn() function automatically uses the hex format when connected to PostgreSQL 9.0 ! or newer servers. --- 2342,2349 whether hex or traditional format is used for bytea output. Libpq's PQescapeByteaConn() function automatically uses the hex format when connected to PostgreSQL 9.0 ! or newer servers. However, pre-9.0 libpq versions will not ! correctly process hex format from newer servers. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7b70970..26f5140 100644 *** a/doc/src/sgml/libpq.sgml --- b/doc/src/sgml/libpq.sgml *** unsigned char *PQescapeByteaConn(PGconn *** 3419,3434 !Certain byte values must be escaped (but all !byte values can be escaped) when used as part !of a bytea literal in an SQL !statement. In general, to escape a byte, it is converted into the !three digit octal number equal to the octet value, and preceded by !usually two backslashes. The single quote (') and backslash !(\) characters have special alternative escape !sequences. See for more !information. PQescapeByteaConn performs this !operation, escaping only the minimally required bytes. --- 3419,3429 !Certain byte values must be escaped when used as part of a !bytea literal in an SQL statement. !PQescapeByteaCon
Re: [DOCS] [GENERAL] Gripe: bytea_output default => data corruption
Bruce Momjian wrote: > ljb wrote: > > [email protected] wrote: > > > I think we should simply remove the description of *how* the escaping is > > > performed, and state only that the function produces a suitably escaped > > > literal string. Anything else is not future-proof, and could someday > > > break the way this wording did. > > > > Perhaps it would be best to remove escaping details here. But the > > description of PQescapeBytea() might need to be rewritten, too. Without > > describing exactly what PQescapeByteaConn() does, it is hard to understand > > what PQescapeBytea() does not do, and why it therefore "might give the > > wrong results". > > > > I think the actual function behavior should be documented somewhere. Even > > though it might change again. > > Based on this report, I have created the attached documentation patch > which clarifies the libpq behavior for escaping bytea. I am planning to > backpatch this to 9.0 as well. My aplogies on the double-attachment. I am now attaching the right verison. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7b70970..26f5140 100644 *** a/doc/src/sgml/libpq.sgml --- b/doc/src/sgml/libpq.sgml *** unsigned char *PQescapeByteaConn(PGconn *** 3419,3434 !Certain byte values must be escaped (but all !byte values can be escaped) when used as part !of a bytea literal in an SQL !statement. In general, to escape a byte, it is converted into the !three digit octal number equal to the octet value, and preceded by !usually two backslashes. The single quote (') and backslash !(\) characters have special alternative escape !sequences. See for more !information. PQescapeByteaConn performs this !operation, escaping only the minimally required bytes. --- 3419,3429 !Certain byte values must be escaped when used as part of a !bytea literal in an SQL statement. !PQescapeByteaConn escapes such bytes using !either hex encoding or backslash escaping. See for more information. *** unsigned char *PQescapeBytea(const unsig *** 3486,3495 The only difference from PQescapeByteaConn is that PQescapeBytea does not take a PGconn parameter. Because of this, it cannot adjust its behavior !depending on the connection properties (in particular, whether !standard-conforming strings are enabled) and therefore !it might give the wrong results. Also, it has no !way to return an error message on failure. --- 3481,3490 The only difference from PQescapeByteaConn is that PQescapeBytea does not take a PGconn parameter. Because of this, it cannot adjust its behavior !depending on the connection properties (e.g. !standard_conforming_strings, bytea_output) !and therefore might give the wrong results. Also, !it has no way to return an error message on failure. diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml index 2288f1b..c43f142 100644 *** a/doc/src/sgml/release-9.0.sgml --- b/doc/src/sgml/release-9.0.sgml *** *** 2342,2348 whether hex or traditional format is used for bytea output. Libpq's PQescapeByteaConn() function automatically uses the hex format when connected to PostgreSQL 9.0 ! or newer servers. --- 2342,2349 whether hex or traditional format is used for bytea output. Libpq's PQescapeByteaConn() function automatically uses the hex format when connected to PostgreSQL 9.0 ! or newer servers. However, pre-9.0 libpq versions will not ! correctly process hex format from newer servers. -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] varname for GUC variables
I have applied the attached patch to use SGML markup consistently for GUC variables. Should we be using to link to more GUC details in the docs? E.g., change: standard_conforming_strings to: -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 0b55446..707bd5a 100644 *** a/doc/src/sgml/datetime.sgml --- b/doc/src/sgml/datetime.sgml *** *** 360,369 ! timezone_abbreviations can be set to any file name found in .../share/timezonesets/, if the file's name is entirely alphabetic. (The prohibition against non-alphabetic ! characters in timezone_abbreviations prevents reading files outside the intended directory, as well as reading editor backup files and other extraneous files.) --- 360,369 ! timezone_abbreviations can be set to any file name found in .../share/timezonesets/, if the file's name is entirely alphabetic. (The prohibition against non-alphabetic ! characters in timezone_abbreviations prevents reading files outside the intended directory, as well as reading editor backup files and other extraneous files.) *** *** 420,426 according to the zoneinfo timezone database. The zone name definitions found in these files can be copied and pasted into a custom configuration file as needed. Note that these files cannot be directly ! referenced as timezone_abbreviations settings, because of the dot embedded in their names. --- 420,426 according to the zoneinfo timezone database. The zone name definitions found in these files can be copied and pasted into a custom configuration file as needed. Note that these files cannot be directly ! referenced as timezone_abbreviations settings, because of the dot embedded in their names. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7b70970..ab09f35 100644 *** a/doc/src/sgml/libpq.sgml --- b/doc/src/sgml/libpq.sgml *** const char *PQparameterStatus(const PGco *** 1418,1463 Parameters reported as of the current release include !server_version, !server_encoding, !client_encoding, !application_name, !is_superuser, !session_authorization, !DateStyle, !IntervalStyle, !TimeZone, !integer_datetimes, and !standard_conforming_strings. !(server_encoding, TimeZone, and !integer_datetimes were not reported by releases before 8.0; !standard_conforming_strings was not reported by releases before 8.1; !IntervalStyle was not reported by releases before 8.4; !application_name was not reported by releases before 9.0.) Note that !server_version, !server_encoding and !integer_datetimes cannot change after startup. Pre-3.0-protocol servers do not report parameter settings, but libpq includes logic to obtain values for !server_version and client_encoding anyway. Applications are encouraged to use PQparameterStatus rather than ad hoc code to determine these values. (Beware however that on a pre-3.0 connection, changing !client_encoding via SET after connection startup will not be reflected by PQparameterStatus.) !For server_version, see also PQserverVersion, which returns the information in a numeric form that is much easier to compare against. !If no value for standard_conforming_strings is reported, applications can assume it is off, that is, backslashes are treated as escapes in string literals. Also, the presence of this parameter can be taken as an indication that the escape string --- 1418,1463 Parameters reported as of the current release include !server_version, !server_encoding, !client_encoding, !application_name, !is_superuser, !session_authorization, !DateStyle, !IntervalStyle, !TimeZone, !integer_datetimes, and !standard_conforming_strings. !(server_encoding, TimeZone, and !integer_datetimes were not reported by releases before 8.0; !standard_conforming_strings was not reported by releases before 8.1; !IntervalStyle was not reported by releases before 8.4; !application_name was not reported by releases before 9.0.) Note that !server_version, !server_encoding and !integer_datetimes cannot change after startup. Pre-3.0-p
Re: [DOCS] varname for GUC variables
Bruce Momjian writes: > I have applied the attached patch to use SGML markup > consistently for GUC variables. Should we be using to link to > more GUC details in the docs? For the most part I think we do have enough links. In particular I do *not* want to see multiple references to the same variable in the same paragraph all turned into links; that's just distracting. regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] varname for GUC variables
Tom Lane wrote: > Bruce Momjian writes: > > I have applied the attached patch to use SGML markup > > consistently for GUC variables. Should we be using to link to > > more GUC details in the docs? > > For the most part I think we do have enough links. In particular I do > *not* want to see multiple references to the same variable in the same > paragraph all turned into links; that's just distracting. True on the multiple instances in a paragraph. I will drop it unless someone feels we need more. Thanks. -- Bruce Momjian 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
Re: [DOCS] Change to documentation headers
Peter, based on feedback we have received, I think our users want our docs header to look the same as our docs footer, i.e. few people see the value of Fast Forward and Fast Backward, and they want "Up" to be in the header. You seem to have done all the substantive changes to stylesheet.dsl --- would you make these changes? Thanks. --- Chris Meller wrote: > I jumped into #postgresql earlier to ask a couple of questions and we > ended up talking about the documentation. agliodbs wanted me to mention > the problems I ran into trying to find what I was looking for on the > mailing list, so here we go. > > I was looking at the documentation (which, btw, has always been of a > very high quality, so props for that!) and trying to find out about > character sets and collations. I didn't have much luck looking at the > main TOC, which isn't a big deal or terribly unexpected, so I did a > search for 'collation'. The second result is the CREATE DATABASE > reference page, which is one of the main pages I was looking for, so > that's great. > > Once I'm there, though, I'm pretty much lost. I've got Prev and Next > links (and Fast Backward and Fast Forward, which didn't seem to do > anything different), but no indication of where I am or how to get > somewhere else. > > For a specific example: After reading the few pieces I needed to know > about for CREATE DATABASE, I wanted to move on to CREATE TABLE. It > looks like I'm in a function reference section, so I assume there must > be a main TOC page listing them all, but I don't see a link to that > anywhere. There's also no indication which chapter and section I'm in, > so I can't go back to the main TOC and navigate down to it to find the > chapter TOC. I ended up hitting 'Next' a dozen times to find CREATE > TABLE in the alphabetical list of functions. > > When I mentioned this out on IRC, peerce did point out that there's an > 'Up' link... at the bottom. I had no idea it was there. I'd found the > parameter I was looking for and had no reason to keep reading the rest > of the lengthy explanation of other parameters and caveats to using > them, so there was no reason for me to keep scrolling and I didn't > expect the navigation link I was looking for to be at the bottom. > > Once I was looking at the navigation at the bottom, it seemed like it > should be the navigation at the top of the page instead. There's an > 'up' link and the Prev and Next links include the title of the pages > you'd be moving to, which is actually nice to know. > > On other pages I saw that the chapter was shown under 'PostgreSQL x.y > Documentation' in the navigation at the top, so I don't know why there > wasn't a similar title on the function page. > > Expanding the breadcrumbs at the top, which only show that you're in > the PostgreSQL x.y documentation, to include the location in the > documentation would pretty much eliminate my problem... So would using > the save left-column navigation bar all the other pages seem to use. > > Anyway, there's my feedback. Great documentation, but confusing > navigation makes it tough to use. Carry on... :) -- Bruce Momjian 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
[DOCS] PL - "Programming Languages" or "Procedural Languages"?
Hi all, I just found "PL" is explained as "Programming Languages" in the Acronyms section. http://www.postgresql.org/docs/current/static/acronyms.html I think this should be "Procedural Languages" because "Procedural" is used in the Server Programming section. http://www.postgresql.org/docs/current/static/server-programming.html I've created a patch, but which should we use? Regards, -- NAGAYASU Satoshi diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index 5dad0db..d1ef489 100644 --- a/doc/src/sgml/acronyms.sgml +++ b/doc/src/sgml/acronyms.sgml @@ -513,7 +513,7 @@ PL - Programming Languages (server-side) + Procedural Languages (server-side) -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
