Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.80) (envelope-from ) id 1WCFed-0007S7-TO for pgsql-docs@arkaria.postgresql.org; Sat, 08 Feb 2014 21:41:40 +0000 Received: from localhost ([127.0.0.1] helo=postgresql.org) by malur.postgresql.org with smtp (Exim 4.80) (envelope-from ) id 1WCFec-0001p2-HD for pgsql-docs@arkaria.postgresql.org; Sat, 08 Feb 2014 21:41:38 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtp (Exim 4.80) (envelope-from ) id 1WCFea-0001od-Ri; Sat, 08 Feb 2014 21:41:36 +0000 Received: from sss.pgh.pa.us ([66.207.139.130]) by magus.postgresql.org with esmtp (Exim 4.80) (envelope-from ) id 1WCFeW-0004jq-BS; Sat, 08 Feb 2014 21:41:36 +0000 Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1]) by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id s18LfGwV014723; Sat, 8 Feb 2014 16:41:17 -0500 From: Tom Lane To: Gavin Flower cc: Peter Eisentraut , Robert Haas , pgsql-hackers@postgresql.org, pgsql-docs@postgresql.org Subject: Re: [HACKERS] Viability of text HISTORY/INSTALL/regression README files (was Re: [COMMITTERS] pgsql: Document a few more regression test hazards.) In-reply-to: <19409.1391842262@sss.pgh.pa.us> References: <22438.1391463522@sss.pgh.pa.us> <28834.1391478486@sss.pgh.pa.us> <52F58CE8.4090902@gmx.net> <18083.1391839531@sss.pgh.pa.us> <52F5D170.4000309@archidevsys.co.nz> <19409.1391842262@sss.pgh.pa.us> Comments: In-reply-to Tom Lane message dated "Sat, 08 Feb 2014 01:51:02 -0500" MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0" Content-ID: <14659.1391895545.0@sss.pgh.pa.us> Date: Sat, 08 Feb 2014 16:41:16 -0500 Message-ID: <14722.1391895676@sss.pgh.pa.us> X-Pg-Spam-Score: -2.5 (--) List-Archive: List-Help: List-ID: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: X-Mailing-List: pgsql-docs Precedence: bulk Sender: pgsql-docs-owner@postgresql.org ------- =_aaaaaaaaaa0 Content-Type: text/plain; charset="us-ascii" Content-ID: <14659.1391895545.1@sss.pgh.pa.us> I wrote: > Gavin Flower 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 ------- =_aaaaaaaaaa0 Content-Type: text/x-diff; name="no-flat-text-release-notes-or-regression-instructions.patch"; charset="us-ascii" Content-ID: <14659.1391895545.2@sss.pgh.pa.us> Content-Description: no-flat-text-release-notes-or-regression-instructions.patch Content-Transfer-Encoding: quoted-printable 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/RE= ADME $(MAKE) -C $(distdir) distclean rm -f $(distdir)/README.git =20=20 --- 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 =20=20 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 +=20 + 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.) =20=20 ! 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 check= out. ! If you are using git, you can view the most recent install instructions a= t: http://www.postgresql.org/docs/devel/static/installation.html - and the current release notes at: - http://www.postgresql.org/docs/devel/static/release.html =20=20 Users compiling from git will also need compatible versions of Bison, Fle= x, and Perl, as discussed in the install documentation. These programs are = not --- 1,12 ---- (This file does not appear in release tarballs.) =20=20 ! 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. !=20 ! 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 =20=20 Users compiling from git will also need compatible versions of Bison, Fle= x, 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 =3D $(JADE) $(JADEFLAGS) $(SGMLI *** 215,247 **** ICONV =3D iconv LYNX =3D lynx =20=20 ! # 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/ $@ =20=20 INSTALL.html: standalone-install.sgml installation.sgml version.sgml $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@ =20=20 - 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 -=20 - regress_README.html: regress.sgml - ( echo ''; \ - echo ' ]>'; \ - cat $< ) >tempfile_regress_README.sgml - $(JADE.text) -V nochunks tempfile_regress_README.sgml > $@ - rm tempfile_regress_README.sgml -=20 =20=20 ## ## XSLT processing --- 215,234 ---- ICONV =3D iconv LYNX =3D lynx =20=20 ! # 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/ $@ =20=20 INSTALL.html: standalone-install.sgml installation.sgml version.sgml $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@ =20=20 =20=20 ## ## 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 =20=20 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 =20=20 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 =3D 15000 *** 942,967 **** Plain Text Files =20=20 ! Several files are distributed as plain text, for reading during ! the installation process. The INSTALL file corresponds to , with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml ! and enter gmake INSTALL. This will create ! a file INSTALL.html that can be saved as text ! with Netscape Navigator and put into ! the place of the existing file. ! Netscape seems to offer the best ! quality for HTML to text conversions (over ! lynx and ! w3m). =20=20 ! The file HISTORY can be created similarly, ! using the command gmake HISTORY. For the ! file src/test/regress/README the command is ! gmake regress_README. =20=20 --- 942,960 ---- Plain Text Files =20=20 ! 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 INSTALL file corresponds to , with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml ! and enter gmake INSTALL. =20=20 ! In the past, the release notes and regression testing instructions ! were also distributed as plain text, but this practice has been ! discontinued. =20=20 diff --git a/doc/src/sgml/generate_history.pl b/doc/src/sgml/generate_histo= ry.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 -=20 - # 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 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 -=20 - use strict; -=20 - my $srcdir =3D shift; - die "$0: missing required argument: srcdir\n" if !defined($srcdir); - my $infile =3D shift; - die "$0: missing required argument: inputfile\n" if !defined($infile); -=20 - # Emit DOCTYPE header so that the output is a self-contained SGML document - print "\n"; -=20 - process_file($infile); -=20 - exit 0; -=20 - sub process_file - { - my $filename =3D shift; -=20 - local *FILE; # need a local filehandle so we can recurse -=20 - my $f =3D $srcdir . '/' . $filename; - open(FILE, $f) || die "could not read $f: $!\n"; -=20 - while () - { -=20 - # Recursively expand sub-files of the release notes - if (m/^&(release-.*);$/) - { - process_file($1 . ".sgml"); - next; - } -=20 - # Remove tags, which might span multiple lines - while (m/]*>//) - { - next; - } -=20 - # incomplete tag, so slurp another line - $_ .=3D ; - } -=20 - # Remove too - s|||g; -=20 - 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 **** =20=20 wrap long lines =20=20 ! For new features, add links to the documentation sections. Use ! 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 . =20=20 --> =20=20 --- 34,40 ---- =20=20 wrap long lines =20=20 ! For new features, add links to the documentation sections. =20=20 --> =20=20 *************** can be created without links to the main *** 71,77 **** =20=20 =20=20 =20=20 s =20=20 * Update timezone data to match latest zic database and new Windows releases, if any (see src/timezone/README) --- 10,15 ---- ------- =_aaaaaaaaaa0 Content-Type: text/plain Content-Disposition: inline Content-Transfer-Encoding: 8bit MIME-Version: 1.0 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs ------- =_aaaaaaaaaa0--