Thread: Viability of text HISTORY/INSTALL/regression README files (was Re: [COMMITTERS] pgsql: Document a few more regression test hazards.)

Robert Haas <robertmhaas@gmail.com> writes:
> On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> guaibasaurus doesn't like this patch: you need to be more careful
>> about links, because the regression instructions are supposed to
>> compile as a standalone document.

> I wonder if these standalone things are really worthwhile.  The whole
> point of this, ten years ago, was that people who were trying to get
> started with PostgreSQL might not have had neither the doc toolchain
> nor convenient Internet access available.  Plain text documentation
> was essential for getting off the ground.  This seems much less
> relevant today; is the annoyance of not being able to use links
> everywhere really buying us anything at this point?

That's a very fair question.  It's a reasonable bet that pretty much
nobody actually looks at the text versions of either HISTORY or
regress_README anymore.  It's conceivable that somebody somewhere makes
use of the text version of INSTALL when trying to get PG going on some
bare-bones platform ... but really, can't they look it up on the net?
How'd they get the PG sources they're installing, anyway?

I'm prepared to believe that these things are just dinosaurs now.
However, at least in the case of the release notes, we'd have to kill them
in all active branches not only HEAD, if we don't want surprises.

Comments?

            regards, tom lane

Noah Misch <noah@leadboat.com> writes:
>> Robert Haas <robertmhaas@gmail.com> writes:
>>> I wonder if these standalone things are really worthwhile.

> I wonder how difficult it would be to make sufficient link data available when
> building the standalone files.  There would be no linking per se; we would
> just need the referent's text fragment emitted where the <xref> tag appears.

IIRC, that's basically what the "workaround" is, except it's not very
automated.  Even if it were automated, though, there's still a problem:
such links aren't really *useful* in flat text format.  I think that
forcing the author to actually think about what to put there in the
flat text version is a good thing, if we're going to retain the flat
text version at all.

            regards, tom lane

On Tue, Feb 4, 2014 at 1:38 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Noah Misch <noah@leadboat.com> writes:
>>> Robert Haas <robertmhaas@gmail.com> writes:
>>>> I wonder if these standalone things are really worthwhile.
>
>> I wonder how difficult it would be to make sufficient link data available when
>> building the standalone files.  There would be no linking per se; we would
>> just need the referent's text fragment emitted where the <xref> tag appears.
>
> IIRC, that's basically what the "workaround" is, except it's not very
> automated.  Even if it were automated, though, there's still a problem:
> such links aren't really *useful* in flat text format.  I think that
> forcing the author to actually think about what to put there in the
> flat text version is a good thing, if we're going to retain the flat
> text version at all.

Right.  I mean, a lot of the links say things like "Section 26.2"
which obviously makes no sense in a standalone text file.

I agree with your comments upthread: INSTALL *might* still be useful
to somebody, but I would be pretty surprised if anyone uses HISTORY or
regress_README for anything any more.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Tue, Feb 4, 2014 at 11:43 PM, Noah Misch <noah@leadboat.com> wrote:
>> Right.  I mean, a lot of the links say things like "Section 26.2"
>> which obviously makes no sense in a standalone text file.
>
> For <xref>s normally displayed that way, text output could emit a URL, either
> inline or in the form of a footnote.  For link targets (e.g. SQL commands)
> having a friendly text fragment for <xref> sites, use the normal fragment.

True.  If we're going to keep these things around, something like that
would avoid some annoyances for documentation authors.  But I still
think we ought to just nuke them, because who cares?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 02/05/2014 07:27 PM, Robert Haas wrote:
> On Tue, Feb 4, 2014 at 11:43 PM, Noah Misch <noah@leadboat.com> wrote:
>>> Right.  I mean, a lot of the links say things like "Section 26.2"
>>> which obviously makes no sense in a standalone text file.
>>
>> For <xref>s normally displayed that way, text output could emit a URL, either
>> inline or in the form of a footnote.  For link targets (e.g. SQL commands)
>> having a friendly text fragment for <xref> sites, use the normal fragment.
>
> True.  If we're going to keep these things around, something like that
> would avoid some annoyances for documentation authors.  But I still
> think we ought to just nuke them, because who cares?

I dont care about HISTORY and even less so about regress_README but I
would prefer to keep INSTALL because I know that people do look at that
one...


Stefan

On Tue, Feb 04, 2014 at 03:28:45PM -0500, Robert Haas wrote:
> On Tue, Feb 4, 2014 at 1:38 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Noah Misch <noah@leadboat.com> writes:
> >>> Robert Haas <robertmhaas@gmail.com> writes:
> >>>> I wonder if these standalone things are really worthwhile.
> >
> >> I wonder how difficult it would be to make sufficient link data available when
> >> building the standalone files.  There would be no linking per se; we would
> >> just need the referent's text fragment emitted where the <xref> tag appears.
> >
> > IIRC, that's basically what the "workaround" is, except it's not very
> > automated.  Even if it were automated, though, there's still a problem:
> > such links aren't really *useful* in flat text format.  I think that
> > forcing the author to actually think about what to put there in the
> > flat text version is a good thing, if we're going to retain the flat
> > text version at all.
>
> Right.  I mean, a lot of the links say things like "Section 26.2"
> which obviously makes no sense in a standalone text file.

For <xref>s normally displayed that way, text output could emit a URL, either
inline or in the form of a footnote.  For link targets (e.g. SQL commands)
having a friendly text fragment for <xref> sites, use the normal fragment.

--
Noah Misch
EnterpriseDB                                 http://www.enterprisedb.com

On Mon, Feb 03, 2014 at 08:48:06PM -0500, Tom Lane wrote:
> Robert Haas <robertmhaas@gmail.com> writes:
> > On Mon, Feb 3, 2014 at 4:38 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> guaibasaurus doesn't like this patch: you need to be more careful
> >> about links, because the regression instructions are supposed to
> >> compile as a standalone document.
>
> > I wonder if these standalone things are really worthwhile.  The whole
> > point of this, ten years ago, was that people who were trying to get
> > started with PostgreSQL might not have had neither the doc toolchain
> > nor convenient Internet access available.  Plain text documentation
> > was essential for getting off the ground.  This seems much less
> > relevant today; is the annoyance of not being able to use links
> > everywhere really buying us anything at this point?
>
> That's a very fair question.  It's a reasonable bet that pretty much
> nobody actually looks at the text versions of either HISTORY or
> regress_README anymore.  It's conceivable that somebody somewhere makes
> use of the text version of INSTALL when trying to get PG going on some
> bare-bones platform ... but really, can't they look it up on the net?
> How'd they get the PG sources they're installing, anyway?

I sometimes read text-based INSTALL files when building other projects, but a
tiny file giving a URL is almost as good.  (The other two generated files do
seem much less important.)

> I'm prepared to believe that these things are just dinosaurs now.
> However, at least in the case of the release notes, we'd have to kill them
> in all active branches not only HEAD, if we don't want surprises.

I wonder how difficult it would be to make sufficient link data available when
building the standalone files.  There would be no linking per se; we would
just need the referent's text fragment emitted where the <xref> tag appears.
For example, have a stylesheet that produces a file bearing all link IDs and
titles appearing anywhere in the documentation.  Let the standalone builds
include that file.

--
Noah Misch
EnterpriseDB                                 http://www.enterprisedb.com

On 2/3/14, 8:48 PM, Tom Lane wrote:
> That's a very fair question.  It's a reasonable bet that pretty much
> nobody actually looks at the text versions of either HISTORY or
> regress_README anymore.  It's conceivable that somebody somewhere makes
> use of the text version of INSTALL when trying to get PG going on some
> bare-bones platform ... but really, can't they look it up on the net?
> How'd they get the PG sources they're installing, anyway?

I think having an INSTALL file is good form, and it costs us little to
maintain it.

The other files could be removed, IMO.

On 2/4/14, 3:28 PM, Robert Haas wrote:
> Right.  I mean, a lot of the links say things like "Section 26.2"
> which obviously makes no sense in a standalone text file.

The man pages have the same issue.  For example from man postgres:

    Other possible file layouts are discussed in Section 18.2, "File
    Locations", in the documentation.

The same could (probably) be done with the INSTALL file.

Peter Eisentraut <peter_e@gmx.net> writes:
> On 2/3/14, 8:48 PM, Tom Lane wrote:
>> That's a very fair question.  It's a reasonable bet that pretty much
>> nobody actually looks at the text versions of either HISTORY or
>> regress_README anymore.  It's conceivable that somebody somewhere makes
>> use of the text version of INSTALL when trying to get PG going on some
>> bare-bones platform ... but really, can't they look it up on the net?
>> How'd they get the PG sources they're installing, anyway?

> I think having an INSTALL file is good form, and it costs us little to
> maintain it.

> The other files could be removed, IMO.

That seems like a reasonable compromise to me.  The HISTORY file is
certainly the worst pain-in-the-rear among these, since it's generated
from files that we change constantly, and so we're always tripping over
the link restrictions.

            regards, tom lane

Gavin Flower <GavinFlower@archidevsys.co.nz> writes:
> How about adding URL's for the online versions of HISTORY & README's (or
> their rough equivalents - perhaps the online version of the latest
> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?

Actually, what I had in mind was to replace the dynamically-generated
HISTORY and README files with small text files that contain those
URL references.  If we remove those files from the distribution
tarballs altogether, it'd likely break some packagers' recipes
(I know for sure it'd break the Red Hat RPM specs, for instance).
But packaging should still work if they're there but smaller.

            regards, tom lane

I wrote:
> Gavin Flower <GavinFlower@archidevsys.co.nz> writes:
>> How about adding URL's for the online versions of HISTORY & README's (or
>> their rough equivalents - perhaps the online version of the latest
>> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?

> Actually, what I had in mind was to replace the dynamically-generated
> HISTORY and README files with small text files that contain those
> URL references.

Here's a proposed patch against HEAD for this.  It also gets rid of some
rather quaint instructions for using Netscape to construct these files ;-)

Barring objection, I'd like to update all the live branches this way
before the upcoming releases.  I'm tired of having to worry about
whether the release notes will build as plain text; but that worry
won't go away unless we nuke the text output in all the branches.

            regards, tom lane

diff --git a/GNUmakefile.in b/GNUmakefile.in
index 40ab280..a573880 100644
*** a/GNUmakefile.in
--- b/GNUmakefile.in
*************** distdir:
*** 103,112 ****
        fi || exit; \
      done
      $(MAKE) -C $(distdir) distprep
!     $(MAKE) -C $(distdir)/doc/src/sgml/ HISTORY INSTALL regress_README
!     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

--- 103,110 ----
        fi || exit; \
      done
      $(MAKE) -C $(distdir) distprep
!     $(MAKE) -C $(distdir)/doc/src/sgml/ INSTALL
      cp $(distdir)/doc/src/sgml/INSTALL $(distdir)/
      $(MAKE) -C $(distdir) distclean
      rm -f $(distdir)/README.git

diff --git a/HISTORY b/HISTORY
index ...360c7f6 .
*** a/HISTORY
--- b/HISTORY
***************
*** 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.
diff --git a/README b/README
index 49d55af..302028e 100644
*** a/README
--- b/README
*************** See the file INSTALL for instructions on
*** 17,24 ****
  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
! 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.
--- 17,23 ----
  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.  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.
diff --git a/README.git b/README.git
index d5378b4..0bf2b56 100644
*** a/README.git
--- b/README.git
***************
*** 1,12 ****
  (This file does not appear in release tarballs.)

! In a release or snapshot tarball of PostgreSQL, documentation files named
! INSTALL and HISTORY will appear in this directory.  However, these files are
! not stored in 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:
      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
--- 1,12 ----
  (This file does not appear in release tarballs.)

! In a release or snapshot tarball of PostgreSQL, a documentation file named
! INSTALL will appear in this directory.  However, this file is not stored in
! git and so will not be present if you are using a git checkout.
!
! 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

  Users compiling from git will also need compatible versions of Bison, Flex,
  and Perl, as discussed in the install documentation.  These programs are not
diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore
index e1b84b4..2f0329c 100644
*** a/doc/src/sgml/.gitignore
--- b/doc/src/sgml/.gitignore
***************
*** 6,14 ****
  /man7/
  /man-stamp
  # Other popular build targets
- /HISTORY
  /INSTALL
- /regress_README
  /postgres-US.pdf
  /postgres-A4.pdf
  /postgres.html
--- 6,12 ----
***************
*** 22,30 ****
  /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
--- 20,26 ----
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index a6a6ef3..304b362 100644
*** a/doc/src/sgml/Makefile
--- b/doc/src/sgml/Makefile
*************** JADE.text = $(JADE) $(JADEFLAGS) $(SGMLI
*** 215,247 ****
  ICONV = iconv
  LYNX = lynx

! # The release notes may contain non-ASCII characters (for contributor
! # names), which lynx converts to the encoding determined by the
! # current locale.  The get 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 are currently 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
      $(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
--- 215,234 ----
  ICONV = iconv
  LYNX = lynx

! # 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' $< | 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 > $@


  ##
  ## XSLT processing
*************** check-tabs:
*** 393,405 ****
  # 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: %-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
  # single-page output
      rm -f postgres.html postgres.txt
  # print
--- 380,392 ----
  # This allows removing some files from the distribution tarballs while
  # keeping the dependencies satisfied.
  .SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index
! .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
!     rm -f INSTALL.html
  # single-page output
      rm -f postgres.html postgres.txt
  # print
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index c9c9862..3cc1d60 100644
*** a/doc/src/sgml/docguide.sgml
--- b/doc/src/sgml/docguide.sgml
*************** save_size.pdfjadetex = 15000
*** 942,967 ****
     <title>Plain Text Files</title>

     <para>
!     Several files are distributed as plain text, for reading during
!     the installation process. 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>).
     </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>.
     </para>
    </sect2>

--- 942,960 ----
     <title>Plain Text Files</title>

     <para>
!     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>.
     </para>

     <para>
!     In the past, the release notes and regression testing instructions
!     were also distributed as plain text, but this practice has been
!     discontinued.
     </para>
    </sect2>

diff --git a/doc/src/sgml/generate_history.pl b/doc/src/sgml/generate_history.pl
index 1d90c67..e69de29 100644
*** a/doc/src/sgml/generate_history.pl
--- b/doc/src/sgml/generate_history.pl
***************
*** 1,65 ****
- #! /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);
- }
--- 0 ----
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index 0980c6e..8cfd57d 100644
*** a/doc/src/sgml/release.sgml
--- b/doc/src/sgml/release.sgml
*************** non-ASCII characters            find usi
*** 34,42 ****

  wrap long lines

! For new features, add links to the documentation sections.  Use </link>
! 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>.

  -->

--- 34,40 ----

  wrap long lines

! For new features, add links to the documentation sections.

  -->

*************** can be created without links to the main
*** 71,77 ****

  <!--
    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.
--- 69,74 ----
diff --git a/doc/src/sgml/standalone-install.sgml b/doc/src/sgml/standalone-install.sgml
index c94b397..1942f9d 100644
*** a/doc/src/sgml/standalone-install.sgml
--- b/doc/src/sgml/standalone-install.sgml
***************
*** 2,22 ****

  <!--
  This file helps in generating the INSTALL text file that lives in the
! top level directory of the distribution. The exact process is like
! 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" [
--- 2,8 ----

  <!--
  This file helps in generating the INSTALL text file that lives in the
! top level directory of the distribution.
  -->

  <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
diff --git a/src/test/regress/README b/src/test/regress/README
index ...0cbf3b6 .
*** a/src/test/regress/README
--- b/src/test/regress/README
***************
*** 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".
diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES
index 321f37c..79a3e19 100644
*** a/src/tools/RELEASE_CHANGES
--- b/src/tools/RELEASE_CHANGES
*************** For All Releases (major, minor, beta, RC
*** 10,16 ****
      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)
--- 10,15 ----

On Sat, Feb 8, 2014 at 4:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I wrote:
>> Gavin Flower <GavinFlower@archidevsys.co.nz> writes:
>>> How about adding URL's for the online versions of HISTORY & README's (or
>>> their rough equivalents - perhaps the online version of the latest
>>> 'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?
>
>> Actually, what I had in mind was to replace the dynamically-generated
>> HISTORY and README files with small text files that contain those
>> URL references.
>
> Here's a proposed patch against HEAD for this.  It also gets rid of some
> rather quaint instructions for using Netscape to construct these files ;-)
>
> Barring objection, I'd like to update all the live branches this way
> before the upcoming releases.  I'm tired of having to worry about
> whether the release notes will build as plain text; but that worry
> won't go away unless we nuke the text output in all the branches.

Sounds OK to me.  If there's as many as two people using those files,
I'll be surprised.  (Of course, I've been surprised before.)

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 08/02/14 19:05, Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
>> On 2/3/14, 8:48 PM, Tom Lane wrote:
>>> That's a very fair question.  It's a reasonable bet that pretty much
>>> nobody actually looks at the text versions of either HISTORY or
>>> regress_README anymore.  It's conceivable that somebody somewhere makes
>>> use of the text version of INSTALL when trying to get PG going on some
>>> bare-bones platform ... but really, can't they look it up on the net?
>>> How'd they get the PG sources they're installing, anyway?
>> I think having an INSTALL file is good form, and it costs us little to
>> maintain it.
>> The other files could be removed, IMO.
> That seems like a reasonable compromise to me.  The HISTORY file is
> certainly the worst pain-in-the-rear among these, since it's generated
> from files that we change constantly, and so we're always tripping over
> the link restrictions.
>
>             regards, tom lane
>
>
How about adding URL's for the online versions of HISTORY & README's (or
their rough equivalents - perhaps the online version of the latest
'Appendix E. Release Notes' would be sufficient?) to the INSTALL file?


Cheers,
Gavin

On 2/8/14, 4:41 PM, Tom Lane wrote:
> diff --git a/HISTORY b/HISTORY
> index ...360c7f6 .
> *** a/HISTORY
> --- b/HISTORY
> ***************
> *** 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

Should be "current" instead of "devel"?

> +
> + 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.

You can point them straight at doc/src/sgml/html/release.html.

Peter Eisentraut <peter_e@gmx.net> writes:
> On 2/8/14, 4:41 PM, Tom Lane wrote:
>> + Release notes for all versions of PostgreSQL can be found on-line at
>> + http://www.postgresql.org/docs/devel/static/release.html

> Should be "current" instead of "devel"?

>> +
>> + 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.

> You can point them straight at doc/src/sgml/html/release.html.

Done and done.  I also noticed that these instructions were wrong anyway
for 8.4, which still has the embedded-tarball HTML docs, so I adjusted
the text for that version.

            regards, tom lane