Remove zero_damaged_pages from postgresql.conf.sample; the only way to

find out about it is to read the documentation that tells you how
dangerous it is.  Add default_transaction_read_only to documentation;
seems to have been overlooked in patch that added read-only transactions.
Clean up check_guc comparison script, which has been suffering bit rot.

doc/src/sgml/runtime.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.175 2003/03/28 20:17:13 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.176 2003/04/03 23:32:47 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -1476,6 +1476,25 @@ SET ENABLE_SEQSCAN TO OFF;
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <indexterm>
+       <primary>read-only transaction</primary>
+      </indexterm>
+
+      <term><varname>DEFAULT_TRANSACTION_READ_ONLY</varname> (<type>boolean</type>)</term>
+      <listitem>
+       <para>
+        A read-only SQL transaction cannot alter non-temporary tables.
+        This parameter controls the default read-only status of each new
+        transaction. The default is false (read/write).
+       </para>
+
+       <para>
+        Consult <xref linkend="sql-set-transaction"> for more information.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><varname>DYNAMIC_LIBRARY_PATH</varname> (<type>string</type>)</term>
       <indexterm><primary>dynamic_library_path</></>
@@ -2182,11 +2201,13 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         <productname>PostgreSQL</> to report an error, aborting the current
 	transaction.  Setting <varname>zero_damaged_pages</> to true causes
 	the system to instead report a warning, zero out the damaged page,
-	and continue processing.  This behavior <emphasis>will lose data</>,
+	and continue processing.  This behavior <emphasis>will destroy data</>,
 	namely all the rows on the damaged page.  But it allows you to get
 	past the error and retrieve rows from any undamaged pages that may
 	be present in the table.  So it is useful for recovering data if
-	corruption has occurred due to hardware or software error.  The
+	corruption has occurred due to hardware or software error.  You should
+	generally not set this true until you have given up hope of recovering
+	data from the damaged page(s) of a table.  The
 	default setting is off, and it can only be changed by a superuser.
        </para>
       </listitem>

src/backend/utils/misc/check_guc

 #!/bin/sh
 
 ## currently, this script makes a lot of assumptions:
-## 1) the valid config settings may be preceded by a '#', but NOT '# '
-##    (we use this to skip comments)
-## 2) the valid config settings will be followed immediately by  ' =' 
-##    (at least one space preceding the '=' for guc.c)
-## 3) the options have PGC_ on the same line as the option
-## 4) the options have '{ ' on the same line as the option
+## in postgresql.conf.sample:
+##   1) the valid config settings may be preceded by a '#', but NOT '# '
+##      (we use this to skip comments)
+##   2) the valid config settings will be followed immediately by  ' =' 
+##      (at least one space preceding the '=')
+## in guc.c:
+##   3) the options have PGC_ on the same line as the option
+##   4) the options have '{' on the same line as the option
 
 ##  Problems
 ## 1) Don't know what to do with TRANSACTION ISOLATION LEVEL
 
-## if an option is valid but shows up in only one file (guc.c or 
-## postgresql.conf.sample, it should be listed here so that it 
+## if an option is valid but shows up in only one file (guc.c but not
+## postgresql.conf.sample), it should be listed here so that it 
 ## can be ignored
 INTENTIONALLY_NOT_INCLUDED="pre_auth_delay lc_messages lc_monetary \
-lc_time lc_numeric server_encoding session_authorization"
+lc_numeric lc_time seed server_encoding session_authorization \
+transaction_isolation transaction_read_only zero_damaged_pages"
 
 ### What options are listed in postgresql.conf.sample, but don't appear 
 ### in guc.c?
@@ -26,19 +29,19 @@ grep -v '^# ' | # strip comments
 sed -e 's/^#//' | 
 awk '{print $1}'`
 
-SETTINGS=`echo "$SETTINGS" | 
-tr 'A-Z' 'a-z' # lowercase`
+SETTINGS=`echo "$SETTINGS" | tr 'A-Z' 'a-z'`
 
 for i in $SETTINGS ; do 
   hidden=0
   ## it sure would be nice to replace this with an sql "not in" statement
-  for hidethis in $INTENTIONALLY_NOT_INCLUDED ; do
-    if [ "$hidethis" = "$i" ] ; then 
-      hidden=1
-    fi
-  done
+  ## it doesn't seem to make sense to have things in .sample and not in guc.c
+#  for hidethis in $INTENTIONALLY_NOT_INCLUDED ; do
+#    if [ "$hidethis" = "$i" ] ; then 
+#      hidden=1
+#    fi
+#  done
   if [ "$hidden" -eq 0 ] ; then
-    grep -i $i guc.c > /dev/null
+    grep -i '"'$i'"' guc.c > /dev/null
     if [ $? -ne 0 ] ; then 
       echo "$i seems to be missing from guc.c"; 
     fi; 
@@ -50,19 +53,21 @@ done
 
 # grab everything that looks like a setting and convert it to lower case
 
-SETTINGS=`grep '{ .*PGC_' guc.c | awk '{print $2}' | \
-          sed -e 's/"//g' -e 's/,//'`
+SETTINGS=`grep '{.* PGC_' guc.c | awk '{print $1}' | \
+          sed -e 's/{//g' -e 's/"//g' -e 's/,//'`
+
 SETTINGS=`echo "$SETTINGS" | tr 'A-Z' 'a-z'`
 
 for i in $SETTINGS ; do
   hidden=0
+  ## it sure would be nice to replace this with an sql "not in" statement
   for hidethis in $INTENTIONALLY_NOT_INCLUDED ; do
     if [ "$hidethis" = "$i" ] ; then
       hidden=1
     fi
   done
   if [ "$hidden" -eq 0 ] ; then
-    grep -i $i postgresql.conf.sample > /dev/null
+    grep -i '#'$i' ' postgresql.conf.sample > /dev/null
     if [ $? -ne 0 ] ; then
       echo "$i seems to be missing from postgresql.conf.sample";
     fi

src/backend/utils/misc/postgresql.conf.sample

@@ -205,6 +205,7 @@
 #authentication_timeout = 60	# 1-600, in seconds
 #deadlock_timeout = 1000	# in milliseconds
 #default_transaction_isolation = 'read committed'
+#default_transaction_read_only = false
 #extra_float_digits = 0		# min -15, max 2
 #max_expr_depth = 10000		# min 10
 #max_files_per_process = 1000	# min 25
@@ -213,6 +214,5 @@
 #sql_inheritance = true
 #transform_null_equals = false
 #statement_timeout = 0		# 0 is disabled, in milliseconds
-#zero_damaged_pages = false     # set this true only for disaster recovery
 #db_user_namespace = false
 #preload_libraries = ''