Merge PostgreSQL 9.2.8 document into Postgres-XC 1.0.4

Author: koichi-szk

doc-xc/src/sgml/.gitignore

@@ -6,9 +6,7 @@
 /man7/
 /man-stamp
 # Other popular build targets
-/HISTORY
 /INSTALL
-/regress_README
 /postgres-US.pdf
 /postgres-A4.pdf
 /postgres.html
@@ -22,9 +20,7 @@
 /HTML.index
 # Assorted byproducts from building the above
 /postgres.xml
-/HISTORY.html
 /INSTALL.html
-/regress_README.html
 /postgres-US.aux
 /postgres-US.log
 /postgres-US.out

doc-xc/src/sgml/Makefile

@@ -231,27 +231,23 @@ INC_LIST = -I PG -I EN
 ##
 
 JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml
+ICONV = iconv
 LYNX = lynx
 
-INSTALL HISTORY regress_README: % : %.html
+# The documentation may contain non-ASCII characters (mostly for
+# contributor names), which lynx converts to the encoding determined
+# by the current locale.  To get text output that is deterministic and
+# easily readable by everyone, we make lynx produce LATIN1 and then
+# convert that to ASCII with transliteration for the non-ASCII characters.
+# Official releases were historically built on FreeBSD, which has limited
+# locale support and is very picky about locale name spelling.  The
+# below has been finely tuned to run on FreeBSD and Linux/glibc.
+INSTALL: % : %.html
 	$(PERL) -p -e 's/<H(1|2)$$/<H\1 align=center/g' $< | $(LYNX) -force_html -dump -nolist -stdin > $@
 
 INSTALL.html: standalone-install.sgml installation.sgml version.sgml
 	$(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@
 
-HISTORY.html: generate_history.pl $(wildcard $(srcdir)/release*.sgml)
-	$(PERL) $< "$(srcdir)" release.sgml >tempfile_HISTORY.sgml
-	$(JADE.text) -V nochunks tempfile_HISTORY.sgml > $@
-	rm tempfile_HISTORY.sgml
-
-regress_README.html: regress.sgml
-	( echo '<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN" ['; \
-	  echo '<!ENTITY % standalone-ignore "IGNORE">'; \
-	  echo '<!ENTITY % standalone-include "INCLUDE"> ]>'; \
-	  cat $< ) >tempfile_regress_README.sgml
-	$(JADE.text) -V nochunks tempfile_regress_README.sgml > $@
-	rm tempfile_regress_README.sgml
-
 
 ##
 ## XSLT processing
@@ -384,13 +380,13 @@ check-tabs:
 # This allows removing some files from the distribution tarballs while
 # keeping the dependencies satisfied.
 .SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index
-.SECONDARY: INSTALL.html HISTORY.html regress_README.html
+.SECONDARY: INSTALL.html
 .SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf
 
 clean:
 # text --- these are shipped, but not in this directory
-	rm -f INSTALL HISTORY regress_README
-	rm -f INSTALL.html HISTORY.html regress_README.html
+	rm -f INSTALL
+	rm -f INSTALL.html
 # single-page output
 	rm -f postgres.html postgres.txt
 # print

doc-xc/src/sgml/backup.sgmlin

@@ -1322,6 +1322,11 @@ tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/
       Please remember to add error handling to your backup scripts.
      </para>
 
+     </sect3>
+
+     <sect3 id="compressed-archive-logs">
+      <title>Compressed Archive Logs</title>
+
      <para>
       If archive storage size is a concern, use <application>pg_compresslog</>,
       <ulink url="http://pglesslog.projects.postgresql.org"></ulink>, to

doc-xc/src/sgml/catalogs.sgmlin

@@ -4669,7 +4669,7 @@
       <entry><structfield>ev_attr</structfield></entry>
       <entry><type>int2</type></entry>
       <entry></entry>
-      <entry>The column this rule is for (currently, always zero to
+      <entry>The column this rule is for (currently, always -1 to
       indicate the whole table)</entry>
      </row>
 

doc-xc/src/sgml/charset.sgmlin

@@ -1606,17 +1606,6 @@ RESET client_encoding;
      systems.
 
      <variablelist>
-      <varlistentry>
-       <term><ulink url="http://www.i18ngurus.com/docs/984813247.html"></ulink></term>
-
-       <listitem>
-        <para>
-         An extensive collection of documents about character sets, encodings,
-         and code pages.
-        </para>
-       </listitem>
-      </varlistentry>
-
       <varlistentry>
        <term><citetitle>CJKV Information Processing: Chinese, Japanese, Korean &amp; Vietnamese Computing</citetitle></term>
 

doc-xc/src/sgml/config.sgmlin

@@ -2108,12 +2108,16 @@ SET ENABLE_SEQSCAN TO OFF;
        </indexterm>
        <listitem>
        <para>
-        Specifies the maximum number of concurrent connections from standby
-        servers or streaming base backup clients (i.e., the maximum number of
-        simultaneously running WAL sender
-        processes). The default is zero. This parameter can only be set at
-        server start. <varname>wal_level</> must be set to <literal>archive</>
-        or <literal>hot_standby</> to allow connections from standby servers.
+        Specifies the maximum number of concurrent connections from
+        standby servers or streaming base backup clients (i.e., the
+        maximum number of simultaneously running WAL sender
+        processes). The default is zero, meaning replication is
+        disabled. WAL sender processes count towards the total number
+        of connections, so the parameter cannot be set higher than
+        <xref linkend="guc-max-connections">.  This parameter can only
+        be set at server start. <varname>wal_level</> must be set
+        to <literal>archive</> or <literal>hot_standby</> to allow
+        connections from standby servers.
        </para>
        </listitem>
       </varlistentry>
@@ -4904,9 +4908,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
        <para>
         This parameter is normally on. When set to <literal>off</>, it
         disables validation of the function body string during <xref
-        linkend="sql-createfunction">. Disabling validation is
-        occasionally useful to avoid problems such as forward references
-        when restoring function definitions from a dump.
+        linkend="sql-createfunction">.  Disabling validation avoids side
+        effects of the validation process and avoids false positives due
+        to problems such as forward references.  Set this parameter
+        to <literal>off</> before loading functions on behalf of other
+        users; <application>pg_dump</> does so automatically.
 <!## XC>
         <note>
          <para>
@@ -5293,6 +5299,7 @@ SET XML OPTION { DOCUMENT | CONTENT };
         partially-significant digits; this is especially useful for dumping
         float data that needs to be restored exactly.  Or it can be set
         negative to suppress unwanted digits.
+        See also <xref linkend="datatype-float">.
        </para>
       </listitem>
      </varlistentry>
@@ -5592,7 +5599,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         just wait on the lock for a while before checking for a
         deadlock. Increasing this value reduces the amount of time
         wasted in needless deadlock checks, but slows down reporting of
-        real deadlock errors. The default is one second (<literal>1s</>),
+        real deadlock errors. The default is one second nheritance(<literal>1s</>),
         which is probably about the smallest value you would want in
         practice. On a heavily loaded server you might want to raise it.
         Ideally the setting should exceed your typical transaction time,
@@ -5872,7 +5879,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       <indexterm><primary>inheritance</></>
       <listitem>
        <para>
-        This controls the inheritance semantics.  If turned <literal>off</>,
+        This setting controls whether undecorated table references are
+        considered to include inheritance child tables.  The default is
+        <literal>on</>, which means child tables are included (thus,
+        a <literal>*</> suffix is assumed by default).  If turned
+        <literal>off</>, child tables are not included (thus, an
+        <literal>ONLY</literal> prefix is assumed).  The SQL standard
+        requires child tables to be included, so the <literal>off</> setting
+        is not spec-compliant, but it is provided for compatibility with
+        <productname>PostgreSQL</> releases prior to 7.1.
+        See <xref linkend="ddl-inherit"> for more information.
+       </para>
+
+       <para>
+        Turning <varname>sql_inheritance</> off is deprecated, because that
+        behavior has been found to be error-prone as well as contrary to SQL
+        standard.  Discussions of inheritance behavior elsewhere in this
+        manual generally assume that it is <literal>on</>.
         subtables are not accessed by various commands by default; basically
         an implied <literal>ONLY</literal> key word.  This was added for
         compatibility with releases prior to 7.1.  See

doc-xc/src/sgml/datatype.sgmlin

@@ -696,6 +696,17 @@ NUMERIC
      from zero will cause an underflow error.
     </para>
 
+    <note>
+     <para>
+      The <xref linkend="guc-extra-float-digits"> setting controls the
+      number of extra significant digits included when a floating point
+      value is converted to text for output.  With the default value of
+      <literal>0</literal>, the output is the same on every platform
+      supported by PostgreSQL.  Increasing it will produce output that
+      more accurately represents the stored value, but may be unportable.
+     </para>
+    </note>
+
     <indexterm>
      <primary>not a number</primary>
      <secondary>double precision</secondary>
@@ -841,6 +852,20 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
      the column, so that it will be dropped if the column or table is dropped.
     </para>
 
+    <note>
+      <para>
+        Because <type>smallserial</type>, <type>serial</type> and
+        <type>bigserial</type> are implemented using sequences, there may
+        be "holes" or gaps in the sequence of values which appears in the
+        column, even if no rows are ever deleted.  A value allocated
+        from the sequence is still "used up" even if a row containing that
+        value is never successfully inserted into the table column.  This
+        may happen, for example, if the inserting transaction rolls back.
+        See <literal>nextval()</literal> in <xref linkend="functions-sequence">
+        for details.
+      </para>
+    </note>
+
     <note>
      <para>
       Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type>

doc-xc/src/sgml/ddl.sgmlin

@@ -2367,6 +2367,23 @@ SELECT name, altitude
    <literal>ONLY</literal> keyword.
   </para>
 
+  <para>
+   You can also write the table name with a trailing <literal>*</>
+   to explicitly specify that descendant tables are included:
+
+<programlisting>
+SELECT name, altitude
+    FROM cities*
+    WHERE altitude &gt; 500;
+</programlisting>
+
+   Writing <literal>*</> is not necessary, since this behavior is
+   the default (unless you have changed the setting of the
+   <xref linkend="guc-sql-inheritance"> configuration option).
+   However writing <literal>*</> might be useful to emphasize that
+   additional tables will be searched.
+  </para>
+
   <para>
    In some cases you might wish to know which table a particular row
    originated from. There is a system column called
@@ -2524,15 +2541,15 @@ VALUES ('New York', NULL, NULL, 'NY');
    data modification, or schema modification
    (e.g., <literal>SELECT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>,
    most variants of <literal>ALTER TABLE</literal>, but
-   not <literal>INSERT</literal> and <literal>ALTER TABLE ...
+   not <literal>INSERT</literal> or <literal>ALTER TABLE ...
    RENAME</literal>) typically default to including child tables and
    support the <literal>ONLY</literal> notation to exclude them.
    Commands that do database maintenance and tuning
    (e.g., <literal>REINDEX</literal>, <literal>VACUUM</literal>)
-   typically only work on individual, physical tables and do no
+   typically only work on individual, physical tables and do not
    support recursing over inheritance hierarchies.  The respective
-   behavior of each individual command is documented in the reference
-   part (<xref linkend="sql-commands">).
+   behavior of each individual command is documented in its reference
+   page (<xref linkend="sql-commands">).
   </para>
 
   <para>
@@ -2582,18 +2599,6 @@ VALUES ('New York', NULL, NULL, 'NY');
    inheritance is useful for your application.
   </para>
 
-  <note>
-   <title>Deprecated</title>
-   <para>
-     In releases of <productname>PostgreSQL</productname> prior to 7.1, the
-     default behavior was not to include child tables in queries. This was
-     found to be error prone and also in violation of the SQL
-     standard.  You can get the pre-7.1 behavior by turning off the
-     <xref linkend="guc-sql-inheritance"> configuration
-     option.
-   </para>
-  </note>
-
    </sect2>
   </sect1>
 

doc-xc/src/sgml/docguide.sgmlin

@@ -1041,26 +1041,19 @@ save_size.pdfjadetex = 15000
 
 &common;
    <para>
-    Several files are distributed as plain text, for reading during
-    the installation process. The <filename>INSTALL</filename> file
+    The installation instructions are also distributed as plain text,
+    in case they are needed in a situation where better reading tools
+    are not available.  The <filename>INSTALL</filename> file
     corresponds to <xref linkend="installation">, with some minor
     changes to account for the different context.  To recreate the
     file, change to the directory <filename>doc/src/sgml</filename>
-    and enter <userinput>gmake INSTALL</userinput>.  This will create
-    a file <filename>INSTALL.html</filename> that can be saved as text
-    with <productname>Netscape Navigator</productname> and put into
-    the place of the existing file.
-    <productname>Netscape</productname> seems to offer the best
-    quality for <acronym>HTML</acronym> to text conversions (over
-    <application>lynx</application> and
-    <application>w3m</application>).
+    and enter <userinput>gmake INSTALL</userinput>.
    </para>
 
    <para>
-    The file <filename>HISTORY</filename> can be created similarly,
-    using the command <userinput>gmake HISTORY</userinput>.  For the
-    file <filename>src/test/regress/README</filename> the command is
-    <userinput>gmake regress_README</userinput>.
+    In the past, the release notes and regression testing instructions
+    were also distributed as plain text, but this practice has been
+    discontinued.
    </para>
   </sect2>
 

doc-xc/src/sgml/ecpg.sgmlin

@@ -951,20 +951,6 @@ struct varchar_var { int len; char arr[180]; } var;
      is used.
     </para>
 
-    <para>
-     Two or more <type>VARCHAR</type> host variables cannot be defined
-     in single line statement.  The following code will confuse
-     the <command>ecpg</command> preprocessor:
-<programlisting>
-VARCHAR v1[128], v2[128];   /* WRONG */
-</programlisting>
-     Two variables should be defined in separate statements like this:
-<programlisting>
-VARCHAR v1[128];
-VARCHAR v2[128];
-</programlisting>
-    </para>
-
     <para>
      <type>VARCHAR</type> can be written in upper or lower case, but
      not in mixed case.
@@ -7742,9 +7728,9 @@ VAR <replaceable>varname</replaceable> IS <replaceable>ctype</replaceable>
     <title>Description</title>
 
     <para>
-     The <command>VAR</command> command defines a host variable.  It
-     is equivalent to an ordinary C variable definition inside a
-     declare section.
+     The <command>VAR</command> command assigns a new C data type
+     to a host variable.  The host variable must be previously
+     declared in a declare section.
     </para>
    </refsect1>
 
@@ -7776,8 +7762,10 @@ VAR <replaceable>varname</replaceable> IS <replaceable>ctype</replaceable>
     <title>Examples</title>
 
 <programlisting>
-EXEC SQL VAR vc IS VARCHAR[10];
-EXEC SQL VAR boolvar IS bool;
+Exec sql begin declare section;
+short a;
+exec sql end declare section;
+EXEC SQL VAR a IS int;
 </programlisting>
    </refsect1>