Don't generate plain-text HISTORY and src/test/regress/README anymore.

Providing this information as plain text was doubtless worth the trouble
ten years ago, but it seems likely that hardly anyone reads it in this
format anymore.  And the effort required to maintain these files (in the
form of extra-complex markup rules in the relevant parts of the SGML
documentation) is significant.  So, let's stop doing that and rely solely
on the other documentation formats.

Per discussion, the plain-text INSTALL instructions might still be worth
their keep, so we continue to generate that file.

Rather than remove HISTORY and src/test/regress/README from distribution
tarballs entirely, replace them with simple stub files that tell the reader
where to find the relevant documentation.  This is mainly to avoid possibly
breaking packaging recipes that expect these files to exist.

Back-patch to all supported branches, because simplifying the markup
requirements for release notes won't help much unless we do it in all
branches.

GNUmakefile.in

@@ -103,10 +103,8 @@ distdir:
 	  fi || exit; \
 	done
 	$(MAKE) -C $(distdir) distprep
-	$(MAKE) -C $(distdir)/doc/src/sgml/ HISTORY INSTALL regress_README
+	$(MAKE) -C $(distdir)/doc/src/sgml/ INSTALL
-	cp $(distdir)/doc/src/sgml/HISTORY $(distdir)/
 	cp $(distdir)/doc/src/sgml/INSTALL $(distdir)/
-	cp $(distdir)/doc/src/sgml/regress_README $(distdir)/src/test/regress/README
 	$(MAKE) -C $(distdir) distclean
 	rm -f $(distdir)/README.git
 

HISTORY

@@ -0,0 +1,6 @@
+Release notes for all versions of PostgreSQL can be found on-line at
+http://www.postgresql.org/docs/devel/static/release.html
+
+In a distribution file set, release notes for the current version can be
+found prebuilt under doc/src/sgml/html/.  Visit the index.html file with
+an HTML browser, then consult the "Release Notes" appendix.

README

@@ -17,8 +17,7 @@ See the file INSTALL for instructions on how to build and install
 PostgreSQL.  That file also lists supported operating systems and
 hardware platforms and contains information regarding any other
 software packages that are required to build or run the PostgreSQL
-system.  Changes between all PostgreSQL releases are recorded in the
+system.  Copyright and license information can be found in the
-file HISTORY.  Copyright and license information can be found in the
 file COPYRIGHT.  A comprehensive documentation set is included in this
 distribution; it can be read as described in the installation
 instructions.

README.git

@@ -1,12 +1,12 @@
 (This file does not appear in release tarballs.)
 
-In a release or snapshot tarball of PostgreSQL, documentation files named
+In a release or snapshot tarball of PostgreSQL, a documentation file named
-INSTALL and HISTORY will appear in this directory.  However, these files are
+INSTALL will appear in this directory.  However, this file is not stored in
-not stored in git and so will not be present if you are using a git checkout.
+git and so will not be present if you are using a git checkout.
-If you are using git, you can view the most recent install instructions at:
+
+If you are using a git checkout, you can view the most recent installation
+instructions at:
 	http://www.postgresql.org/docs/devel/static/installation.html
-and the current release notes at:
-	http://www.postgresql.org/docs/devel/static/release.html
 
 Users compiling from git will also need compatible versions of Bison, Flex,
 and Perl, as discussed in the install documentation.  These programs are not

doc/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/src/sgml/Makefile

@@ -215,33 +215,20 @@ JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i
 ICONV = iconv
 LYNX = lynx
 
-# The release notes may contain non-ASCII characters (for contributor
+# The documentation may contain non-ASCII characters (mostly for
-# names), which lynx converts to the encoding determined by the
+# contributor names), which lynx converts to the encoding determined
-# current locale.  The get output that is deterministic and easily
+# by the current locale.  To get text output that is deterministic and
-# readable by everyone, we make lynx produce LATIN1 and then convert
+# easily readable by everyone, we make lynx produce LATIN1 and then
-# that to ASCII with transliteration for the non-ASCII characters.
+# convert that to ASCII with transliteration for the non-ASCII characters.
-# Official releases are currently built on FreeBSD, which has limited
+# 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 HISTORY regress_README: % : %.html
+INSTALL: % : %.html
 	$(PERL) -p -e 's/<H(1|2)$$/<H\1 align=center/g' $< | LC_ALL=en_US.ISO8859-1 $(LYNX) -force_html -dump -nolist -stdin | $(ICONV) -f latin1 -t us-ascii//TRANSLIT > $@
 
 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
@@ -393,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
-	rm -f INSTALL.html HISTORY.html regress_README.html
+	rm -f INSTALL.html
 # single-page output
 	rm -f postgres.html postgres.txt
 # print

doc/src/sgml/docguide.sgml

@@ -942,26 +942,19 @@ save_size.pdfjadetex = 15000
    <title>Plain Text Files</title>
 
    <para>
-    Several files are distributed as plain text, for reading during
+    The installation instructions are also distributed as plain text,
-    the installation process. The <filename>INSTALL</filename> file
+    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
+    and enter <userinput>gmake INSTALL</userinput>.
-    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>).
    </para>
 
    <para>
-    The file <filename>HISTORY</filename> can be created similarly,
+    In the past, the release notes and regression testing instructions
-    using the command <userinput>gmake HISTORY</userinput>.  For the
+    were also distributed as plain text, but this practice has been
-    file <filename>src/test/regress/README</filename> the command is
+    discontinued.
-    <userinput>gmake regress_README</userinput>.
    </para>
   </sect2>
 

doc/src/sgml/generate_history.pl

@@ -1,65 +0,0 @@
-#! /usr/bin/perl -w
-
-# generate_history.pl -- flatten release notes for use as HISTORY file
-#
-# Usage: generate_history.pl srcdir release.sgml >output.sgml
-#
-# The main point of this script is to strip out <link> references, which
-# generally point into the rest of the documentation and so can't be used
-# in a standalone build of the release notes.  To make sure this is done
-# everywhere, we have to fold in the sub-files of the release notes.
-#
-# doc/src/sgml/generate_history.pl
-
-use strict;
-
-my $srcdir = shift;
-die "$0: missing required argument: srcdir\n" if !defined($srcdir);
-my $infile = shift;
-die "$0: missing required argument: inputfile\n" if !defined($infile);
-
-# Emit DOCTYPE header so that the output is a self-contained SGML document
-print "<!DOCTYPE appendix PUBLIC \"-//OASIS//DTD DocBook V4.2//EN\">\n";
-
-process_file($infile);
-
-exit 0;
-
-sub process_file
-{
-	my $filename = shift;
-
-	local *FILE;    # need a local filehandle so we can recurse
-
-	my $f = $srcdir . '/' . $filename;
-	open(FILE, $f) || die "could not read $f: $!\n";
-
-	while (<FILE>)
-	{
-
-		# Recursively expand sub-files of the release notes
-		if (m/^&(release-.*);$/)
-		{
-			process_file($1 . ".sgml");
-			next;
-		}
-
-		# Remove <link ...> tags, which might span multiple lines
-		while (m/<link/)
-		{
-			if (s/<link\s+linkend[^>]*>//)
-			{
-				next;
-			}
-
-			# incomplete tag, so slurp another line
-			$_ .= <FILE>;
-		}
-
-		# Remove </link> too
-		s|</link>||g;
-
-		print;
-	}
-	close(FILE);
-}

doc/src/sgml/release.sgml

@@ -34,9 +34,7 @@ non-ASCII characters            find using grep -P '[\x80-\xFF]'
 
 wrap long lines
 
-For new features, add links to the documentation sections.  Use </link>
+For new features, add links to the documentation sections.
-not just </> so that generate_history.pl can remove it, so HISTORY.html
-can be created without links to the main documentation.  Don't use <xref>.
 
 -->
 
@@ -71,7 +69,6 @@ can be created without links to the main documentation.  Don't use <xref>.
 
 <!--
   To add a new major-release series, add an entry here and in filelist.sgml.
-  Follow the naming convention, or you'll confuse generate_history.pl.
 
   The reason for splitting the release notes this way is so that appropriate
   subsets can easily be copied into back branches.

doc/src/sgml/standalone-install.sgml

@@ -2,21 +2,7 @@
 
 <!--
 This file helps in generating the INSTALL text file that lives in the
-top level directory of the distribution. The exact process is like
+top level directory of the distribution.
-this:
-
-1. Paste together with installation.sgml
-
-2. Process with jade to HTML (use -V nochunks)
-
-3. Remove "Chapter 1" heading
-
-4. Save as text file in Netscape
-
-5. Put in place of old INSTALL file
-
-Running 'make INSTALL' in the doc/src/sgml directory will do 1 through
-3 for you.
 -->
 
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [

src/test/regress/README

@@ -0,0 +1,3 @@
+Documentation concerning how to run these regression tests and interpret
+the results can be found in the PostgreSQL manual, in the chapter
+"Regression Tests".

src/tools/RELEASE_CHANGES

@@ -10,7 +10,6 @@ For All Releases (major, minor, beta, RC)
 	o update doc/src/sgml/release.sgml
 	o run spellchecker on result
 	o add SGML markup
-	o check if 'gmake HISTORY.html' works for <link>s
 
 * Update timezone data to match latest zic database and new
   Windows releases, if any (see src/timezone/README)