Re: [DOCS] Grammar and formatting errors for 9.02 pdf version
Excerpts from Robert Haas's message of mar dic 21 23:33:19 -0300 2010: > With respect to formatting errors, we tend to worry more about the > HTML versions of the docs than the PDF. That said, we have certainly made some changes to the text to better acommodate the PDF output, particularly where program output is too wide to fit the page, which is more common than we'd like. > However, you should certainly > point out what you have noticed so that we can try to determine > whether anything can be done to improve the situation. What Robert said. -- Álvaro Herrera The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Grammar and formatting errors for 9.02 pdf version
--- On Tue, 12/21/10, Robert Haas wrote: From: Robert Haas Subject: Re: [DOCS] Grammar and formatting errors for 9.02 pdf version To: "Leslie S Satenstein" Cc: "pgsql-docs" Date: Tuesday, December 21, 2010, 10:56 PM On Tue, Dec 21, 2010 at 10:43 PM, Leslie S Satenstein wrote: > > Hi Robert, I am not familiar with your patch process. However, I can copy > and paste the offending lines in the PDF file, to a word or openoffice > document, and use green for insert and red text for delete and yellow for > elaboration or comments. And of course, as well, to identify the page from > the pdf guide. > > Some text, if rephrased, makes the meaning more clear. Some text has missing > nouns and where several nouns precede a pronoun, it causes a delay as one > stops to analyze the sentence in order to extract the author's meaning. > > If there is a better way, please advise me. Please keep replies on-list, and write your replies beneath the quoted text rather than above it. To submit a patch, you need to check out the source code, edit the SGML documentation, and then use git diff. See: http://wiki.postgresql.org/wiki/Submitting_a_Patch In short: git clone git://git.postgresql.org/git/postgresql.git git diff > grammar.patch If you have only a handful of changes, feel free to just point out the parts that you think could be phrased better and how you think they should be written, rather than generating a patch. Actually, it'd probably be better to point out the first few changes that way anyhow, to see if we agree with your opinions on what should be done. If you're submitting a large number of edits, you're going to have to learn how to generate a patch file as per the above, because otherwise it's going to be extremely laborious for anyone to think about applying your changes. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company Hi Robert. Since Yahoo.com does not allow me to respond as an append, please excuse the formatting that takes place in the left margin. For this time, please use html for reading this email. Here is an example of how I was thinking to proceed but using a word document so that formatting would be respected. I would present the page in word, and then identify the changes with red/green. To keep this email short, I am showing only a very few changes. Green is for an insertion, Red is for a deletion. Yellow is for clarification PDF 9.02 Page 591, bottom tty Ignored (formerly, this parameter specified where to send server debug output). Word parameter is inserted. Page 594 Text below is truncated as it goes beyond the right margin Make a connection to the database server in a nonblocking manner. PGconn *PQconnectStartParams(const char **keywords, const char **values, int expand_dbname); Page 595 To begin a nonblocking connection callexecute conn = Further down IfAfter PQconnectStart succeeds ... Leaving the opening If . in my mind says, what to do if it does not succeed then what? By writing after PQConnectStart succeeds... takes away liability. There is some rewording that I would do on later pages. Why do I bring these changes up for review, because of Latin readers (French/ Spanish readers are translating the English and therefore good precision is needed). Living in Quebec Canada, and doing business in Latin America, I have become trilingual and write software and documentation in these additional languages. Oh yes, in this chapter 31, protocol is mentioned several times. But the very first time protocol is defined or explained is in chapter 46. I believe that a forward reference is required before the first mention of this property (page 602). Regards Bien à vous Leslie
[DOCS] OID
I am reading the PDF document and ran into the term OID in the section 4.2.11. Array Constructors However, OID is first defined in Chapter 5. (5.4 System Columns). Is it reasonable to perhaps move the contents of or repeat part of the contents of section 5.4 in sectioln 4.2.11? Is this unreferenced term that appears earlier than the definition considered a document bug?. -- Regards Leslie Mr. Leslie Satenstein mailto:[email protected] mailto [email protected] / [email protected] www.itbms.biz
[DOCS] Addition to TOAST documentation in 8.4 comprehensive manual
Hello, I'd like to suggest a small addition to the TOAST overview in the 8.4 comprehensive manual, Chapter 53.2 TOAST. This is my first doc patch for postgres, so if this is not appropriate, please advise. I spent almost an hour trying to figure out how to go from the TOAST table id to the owning table name... finally got help on #postgresql. Thought I'd document it for other sys admins new to PostgreSQL. Or is this something that would be better to go into the PostgreSQL Wiki? Sincerely, Aleksey To find the parent table given a TOAST table, which has a name like pg_toast_12513885, cast the OID of the toast table to "regclass". For example: Given "monkeys" table which spills over to pg_toast_12513885: select 12513885::regclass; regclass -- monkeys (1 row) "regclass" stands for registered "class". Per RhodiumToad on #postgresql, for reasons too complicated to explain, "class" is used to mean "relation". Reference: "casting a table's OID to regclass is handy for symbolic display of a numeric OID" http://www.postgresql.org/docs/8.4/static/datatype-oid.html -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Addition to TOAST documentation in 8.4 comprehensive manual
I'd like to add the following to my proposed documentation tidbit, please: The more offical/strict way, that does not rely on the implementation artifact that TOAST numeric ID is embedded in the TOAST symbolic name, is: select oid::regclass from pg_class where reltoastrelid='pg_toast_12513885'::regclass; Thanks for a world class database! Sincerely, Aleksey -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] OID
Leslie S Satenstein writes: > Is this unreferenced term that appears earlier than the definition considered > a document bug?. No. It would be completely impractical, or at least unintelligible, to write the manual with no forward references whatsoever. regards, tom lane -- Sent via pgsql-docs mailing list ([email protected]) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
