Stop generating plain-text INSTALL instructions.

Up to now, our distribution tarballs have included a plain-text form
of the installation.sgml chapter.  The rationale for that was that a
recipient might not have either ready internet access or HTML-viewing
tools; a theory that seems downright quaint today.  Maintaining the
ability to generate this file is not without cost, because it puts
special requirements on installation.sgml that are often overlooked.
Moreover, we are moving in the direction of making our distribution
tarballs be pure git snapshots for traceability/reproducibility
reasons; including generated files doesn't fit into that plan.
Hence, let's just drop INSTALL and remove the infrastructure for
generating it.  The top-level README will now recommend visiting
our website to see the installation instructions.  As a useful
side-effect, we can get rid of README.git which has provoked
confusion.

Discussion: https://postgr.es/m/20231220114927.faccqqprmuyrzdip@alap3.anarazel.de
Discussion: https://postgr.es/m/e07408d9-e5f2-d9fd-5672-f53354e9305e@eisentraut.org

Author: tglsfdc

GNUmakefile.in

@@ -109,10 +109,7 @@ distdir:
 	      || cp "$(top_srcdir)/$$file" "$(distdir)/$$file"; \
 	  fi || exit; \
 	done
-	$(MAKE) -C $(distdir)/doc/src/sgml/ INSTALL
-	cp $(distdir)/doc/src/sgml/INSTALL $(distdir)/
 	$(MAKE) -C $(distdir) distclean
-	rm -f $(distdir)/README.git
 
 distcheck: dist
 	rm -rf $(dummy)

Makefile

@@ -17,13 +17,7 @@ all:
 
 all check install installdirs installcheck installcheck-parallel uninstall clean distclean maintainer-clean dist distcheck world check-world install-world installcheck-world:
 	@if [ ! -f GNUmakefile ] ; then \
-	   if [ -f INSTALL ] ; then \
-	     INSTRUCTIONS="INSTALL"; \
-	   else \
-	     INSTRUCTIONS="README.git"; \
-	   fi; \
-	   echo "You need to run the 'configure' program first. See the file"; \
-	   echo "'$$INSTRUCTIONS' for installation instructions, or visit: " ; \
+	   echo "You need to run the 'configure' program first. Please see"; \
 	   echo "<https://www.postgresql.org/docs/devel/installation.html>" ; \
 	   false ; \
 	 fi

README

@@ -9,14 +9,13 @@ that supports an extended subset of the SQL standard, including
 transactions, foreign keys, subqueries, triggers, user-defined types
 and functions.  This distribution also contains C language bindings.
 
-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.  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.
+Copyright and license information can be found in the file COPYRIGHT.
+
+General documentation about this version of PostgreSQL can be found at:
+https://www.postgresql.org/docs/devel/
+In particular, information about building PostgreSQL from the source
+code can be found at:
+https://www.postgresql.org/docs/devel/installation.html
 
 The latest version of this software, and related software, may be
 obtained at https://www.postgresql.org/download/.  For more information

README.git

@@ -6,7 +6,6 @@
 /man7/
 /man-stamp
 # Other popular build targets
-/INSTALL
 /postgres-US.pdf
 /postgres-A4.pdf
 /postgres.html
@@ -21,7 +20,5 @@
 /wait_event_types.sgml
 # Assorted byproducts from building the above
 /postgres-full.xml
-/INSTALL.html
-/INSTALL.xml
 /postgres-US.fo
 /postgres-A4.fo

doc/src/sgml/.gitignore

@@ -36,6 +36,8 @@ ifndef FOP
 FOP = $(missing) fop
 endif
 
+PANDOC = pandoc
+
 XMLINCLUDE = --path . --path $(srcdir)
 
 ifdef XMLLINT
@@ -113,25 +115,6 @@ wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names
 targets-meson.sgml: targets-meson.txt $(srcdir)/generate-targets-meson.pl
 	$(PERL) $(srcdir)/generate-targets-meson.pl $^ > $@
 
-##
-## Generation of some text files.
-##
-
-ICONV = iconv
-PANDOC = pandoc
-
-INSTALL: % : %.html
-	$(PANDOC) -t plain -o $@.tmp $<
-	$(ICONV) -f utf8 -t us-ascii//TRANSLIT $@.tmp > $@
-	rm $@.tmp
-
-INSTALL.html: %.html : stylesheet-text.xsl %.xml
-	$(XMLLINT) --noout --valid $*.xml
-	$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@
-
-INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres-full.xml
-	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@
-
 
 ##
 ## HTML
@@ -284,13 +267,9 @@ check-tabs:
 # keeping the dependencies satisfied.
 .SECONDARY: $(GENERATED_SGML)
 .SECONDARY: postgres-full.xml
-.SECONDARY: INSTALL.html INSTALL.xml
 .SECONDARY: postgres-A4.fo postgres-US.fo
 
 clean:
-# text --- these are shipped, but not in this directory
-	rm -f INSTALL
-	rm -f INSTALL.html INSTALL.xml
 # single-page output
 	rm -f postgres.html postgres.txt
 # print

doc/src/sgml/Makefile

@@ -393,28 +393,6 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
    </para>
   </sect2>
 
-  <sect2 id="docguide-build-plain-text">
-   <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>make INSTALL</userinput>.  Building text output
-    requires <productname>Pandoc</productname> version 1.13 or newer as an
-    additional build tool.
-   </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>
-
   <sect2 id="docguide-build-syntax-check">
    <title>Syntax Check</title>
 

doc/src/sgml/docguide.sgml

@@ -1,12 +1,4 @@
 <!-- doc/src/sgml/installation.sgml -->
-<!--
-
-The standalone version has some portions that are different from the version
-that is integrated into the full documentation set, in particular as regards
-links, so that INSTALL.html can be created without links to the main
-documentation.  See standalone-profile.xsl for details.
-
--->
 
 <chapter id="installation">
  <title>Installation from Source Code</title>
@@ -15,7 +7,6 @@ documentation.  See standalone-profile.xsl for details.
   <primary>installation</primary>
  </indexterm>
 
- <!-- See also the version of this text in standalone-install.xml -->
  <para>
   This chapter describes the installation of
   <productname>PostgreSQL</productname> using the source code
@@ -942,9 +933,7 @@ build-postgresql:
        <listitem>
         <para>
          Build with support for <productname>LLVM</productname> based
-         <acronym>JIT</acronym> compilation<phrase
-         condition="standalone-ignore"> (see <xref
-         linkend="jit"/>)</phrase>.  This
+         <acronym>JIT</acronym> compilation (see <xref linkend="jit"/>).  This
          requires the <productname>LLVM</productname> library to be installed.
          The minimum required version of <productname>LLVM</productname> is
          currently 3.9.
@@ -1085,8 +1074,8 @@ build-postgresql:
          for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
          service notifications.  This improves integration if the server
          is started under <application>systemd</application> but has no impact
-         otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
-         information</phrase>.  <application>libsystemd</application> and the
+         otherwise; see <xref linkend="server-start"/> for more
+         information.  <application>libsystemd</application> and the
          associated header files need to be installed to use this option.
         </para>
        </listitem>
@@ -1224,9 +1213,8 @@ build-postgresql:
         <para>
          Build without support for the
          <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
-         library, disabling the use of ICU collation features<phrase
-         condition="standalone-ignore"> (see <xref
-         linkend="collation"/>)</phrase>.
+         library, disabling the use of ICU collation features (see <xref
+         linkend="collation"/>).
         </para>
        </listitem>
       </varlistentry>
@@ -1583,7 +1571,7 @@ build-postgresql:
         <para>
          Enable tests using the Perl TAP tools.  This requires a Perl
          installation and the Perl module <literal>IPC::Run</literal>.
-         <phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase>
+         See <xref linkend="regress-tap"/> for more information.
         </para>
        </listitem>
       </varlistentry>
@@ -1610,8 +1598,8 @@ build-postgresql:
          code coverage testing instrumentation.  When run, they
          generate files in the build directory with code coverage
          metrics.
-         <phrase condition="standalone-ignore">See <xref linkend="regress-coverage"/>
-         for more information.</phrase> This option is for use only with GCC
+         See <xref linkend="regress-coverage"/>
+         for more information. This option is for use only with GCC
          and when doing development work.
         </para>
        </listitem>
@@ -1639,8 +1627,7 @@ build-postgresql:
          </indexterm>
          Compiles <productname>PostgreSQL</productname> with support for the
          dynamic tracing tool DTrace.
-         <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
-         for more information.</phrase>
+         See <xref linkend="dynamic-trace"/> for more information.
         </para>
 
         <para>
@@ -2406,9 +2393,8 @@ ninja install
        <para>
         Build with support for the
         <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
-        library, enabling use of ICU collation features<phrase
-        condition="standalone-ignore"> (see <xref
-        linkend="collation"/>)</phrase>.  Defaults to auto and requires the
+        library, enabling use of ICU collation features (see <xref
+        linkend="collation"/>).  Defaults to auto and requires the
         <productname>ICU4C</productname> package to be installed.  The minimum
         required version of <productname>ICU4C</productname> is currently 4.2.
        </para>
@@ -2420,8 +2406,7 @@ ninja install
       <listitem>
        <para>
         Build with support for <productname>LLVM</productname> based
-        <acronym>JIT</acronym> compilation<phrase
-        condition="standalone-ignore"> (see <xref linkend="jit"/>)</phrase>.
+        <acronym>JIT</acronym> compilation (see <xref linkend="jit"/>).
         This requires the <productname>LLVM</productname> library to be
         installed.  The minimum required version of
         <productname>LLVM</productname> is currently 3.9.  Disabled by
@@ -2546,8 +2531,8 @@ ninja install
         <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
         service notifications.  This improves integration if the server is
         started under <application>systemd</application> but has no impact
-        otherwise<phrase condition="standalone-ignore">; see <xref
-        linkend="server-start"/> for more information</phrase>.  Defaults to
+        otherwise; see <xref
+        linkend="server-start"/> for more information.  Defaults to
         auto.  <application>libsystemd</application> and the associated header
         files need to be installed to use this option.
        </para>
@@ -3122,8 +3107,7 @@ ninja install
        <para>
         Enable tests using the Perl TAP tools.  Defaults to auto and requires
         a Perl installation and the Perl module <literal>IPC::Run</literal>.
-        <phrase condition="standalone-ignore">See <xref
-        linkend="regress-tap"/> for more information.</phrase>
+        See <xref linkend="regress-tap"/> for more information.
        </para>
       </listitem>
      </varlistentry>
@@ -3147,8 +3131,8 @@ ninja install
         code coverage testing instrumentation.  When run, they
         generate files in the build directory with code coverage
         metrics.
-        <phrase condition="standalone-ignore">See <xref linkend="regress-coverage"/>
-        for more information.</phrase> This option is for use only with GCC
+        See <xref linkend="regress-coverage"/>
+        for more information. This option is for use only with GCC
         and when doing development work.
        </para>
       </listitem>
@@ -3163,8 +3147,7 @@ ninja install
         </indexterm>
         Enabling this compiles <productname>PostgreSQL</productname> with support for the
         dynamic tracing tool DTrace.
-        <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
-        for more information.</phrase>
+        See <xref linkend="dynamic-trace"/> for more information.
        </para>
 
        <para>

doc/src/sgml/installation.sgml

@@ -182,43 +182,6 @@ if docs_dep.found()
 endif
 
 
-#
-# INSTALL in html, text
-#
-if docs_dep.found()
-  # Depend on postgres_full_xml, so validity errors are raised in one place,
-  # and so dependencies don't need to be re-specified.
-  install_xml = custom_target('INSTALL.xml',
-    input: ['standalone-profile.xsl', 'standalone-install.xml'],
-    output: 'INSTALL.xml',
-    depfile: 'INSTALL.xml.d',
-    depends: postgres_full_xml,
-    command: [xsltproc, '-o', '@OUTPUT@', xsltproc_flags, '--xinclude', '@INPUT@'],
-    build_by_default: false,
-  )
-  install_html = custom_target('INSTALL.html',
-    input: ['stylesheet-text.xsl', install_xml],
-    output: 'INSTALL.html',
-    depfile: 'INSTALL.html.d',
-    command: [xsltproc, '-o', '@OUTPUT@', xsltproc_html_flags, '@INPUT@'],
-    build_by_default: false,
-  )
-  alldocs += install_html
-
-  if pandoc.found()
-    # XXX: Makefile does an iconv translit here, but unclear why?
-    install = custom_target('INSTALL',
-      input: [install_html],
-      output: 'INSTALL',
-      command: [pandoc, '-t', 'plain', '-o', '@OUTPUT@', '@INPUT@'],
-      build_by_default: false,
-    )
-    alldocs += install
-  endif
-
-endif
-
-
 #
 # Man pages
 #