Обсуждение: ci: Build standalone INSTALL file

Hi,

We fairly regularly have commits breaking the generation of INSTALL. IIRC we
recently discussed building it locally unconditionally, but I couldn't
immediately find that discussion.  Until then, I think we should at least
build it in CI so that cfbot can warn.

Greetings,

Andres Freund

Hi,

The attached patch had a slight bug. Also turned out that the CI environment
didn't have pandoc installed. Fixed that.

Greetings,

Andres Freund

> On 20 Dec 2023, at 15:15, Andres Freund <andres@anarazel.de> wrote:

> The attached patch had a slight bug. Also turned out that the CI environment
> didn't have pandoc installed. Fixed that.

LGTM.

+      time make -s -j${BUILD_JOBS} -C doc/src/sgml all INSTALL
unrelated pet peeve: "make -C doc/src/sgml all" doesn't build all docs targets..

--
Daniel Gustafsson

Andres Freund <andres@anarazel.de> writes:
> We fairly regularly have commits breaking the generation of INSTALL. IIRC we
> recently discussed building it locally unconditionally, but I couldn't
> immediately find that discussion.  Until then, I think we should at least
> build it in CI so that cfbot can warn.

I thought the plan was to get rid of that file, in pursuit of making
our distribution tarballs be more or less pure git pulls.  Instead of
expending more effort on it, why not just push that project forward?
(IIRC, what we intended to do instead was to modify the top-level
README to point at the HTML install directions on the web.)

            regards, tom lane

On Wed, Dec 20, 2023 at 11:36:28AM -0500, Tom Lane wrote:
> Andres Freund <andres@anarazel.de> writes:
>> We fairly regularly have commits breaking the generation of INSTALL. IIRC we
>> recently discussed building it locally unconditionally, but I couldn't
>> immediately find that discussion.  Until then, I think we should at least
>> build it in CI so that cfbot can warn.
>
> I thought the plan was to get rid of that file, in pursuit of making
> our distribution tarballs be more or less pure git pulls.  Instead of
> expending more effort on it, why not just push that project forward?
> (IIRC, what we intended to do instead was to modify the top-level
> README to point at the HTML install directions on the web.)

Hmm.  It depends on if the next release should include it or not, but
let me add my +1 for replacing it with a simple redirect.
--
Michael

On Wed, Dec 20, 2023 at 03:28:56PM +0100, Daniel Gustafsson wrote:
> +      time make -s -j${BUILD_JOBS} -C doc/src/sgml all INSTALL
> unrelated pet peeve: "make -C doc/src/sgml all" doesn't build all docs targets..

That seems relevant in terms of coverage.  Why not just moving the
INSTALL bit to a different line?
--
Michael

On 2023-12-21 08:44:33 +0900, Michael Paquier wrote:
> On Wed, Dec 20, 2023 at 03:28:56PM +0100, Daniel Gustafsson wrote:
> > +      time make -s -j${BUILD_JOBS} -C doc/src/sgml all INSTALL
> > unrelated pet peeve: "make -C doc/src/sgml all" doesn't build all docs targets..
> 
> That seems relevant in terms of coverage.  Why not just moving the
> INSTALL bit to a different line?

I am confused - which coverage could we be loosing here?

Hi,

On 2023-12-20 15:28:56 +0100, Daniel Gustafsson wrote:
> +      time make -s -j${BUILD_JOBS} -C doc/src/sgml all INSTALL
> unrelated pet peeve: "make -C doc/src/sgml all" doesn't build all docs targets..

Well, building the PDF takes a *long* time and is rarely required. I think
there's an argument for adding INSTALL to all - however, there's a reason not
to as well: It has pandoc as an additional dependency, which isn't small...

Andres

Hi,

On 2023-12-21 08:39:26 +0900, Michael Paquier wrote:
> On Wed, Dec 20, 2023 at 11:36:28AM -0500, Tom Lane wrote:
> > Andres Freund <andres@anarazel.de> writes:
> >> We fairly regularly have commits breaking the generation of INSTALL. IIRC we
> >> recently discussed building it locally unconditionally, but I couldn't
> >> immediately find that discussion.  Until then, I think we should at least
> >> build it in CI so that cfbot can warn.
> > 
> > I thought the plan was to get rid of that file, in pursuit of making
> > our distribution tarballs be more or less pure git pulls.  Instead of
> > expending more effort on it, why not just push that project forward?
> > (IIRC, what we intended to do instead was to modify the top-level
> > README to point at the HTML install directions on the web.)

Ah, right.  I don't really care what solution we go for, just that as long as
we have INSTALL, we should make sure we don't regularly break it... Both
Michael and I have in the last couple weeks.


> Hmm.  It depends on if the next release should include it or not, but
> let me add my +1 for replacing it with a simple redirect.

Are you going to submit a patch for that bit?

Greetings,

Andres Freund

> On 21 Dec 2023, at 10:16, Andres Freund <andres@anarazel.de> wrote:
>
> Hi,
>
> On 2023-12-20 15:28:56 +0100, Daniel Gustafsson wrote:
>> +      time make -s -j${BUILD_JOBS} -C doc/src/sgml all INSTALL
>> unrelated pet peeve: "make -C doc/src/sgml all" doesn't build all docs targets..
>
> Well, building the PDF takes a *long* time and is rarely required. I think
> there's an argument for adding INSTALL to all - however, there's a reason not
> to as well: It has pandoc as an additional dependency, which isn't small...

Yeah, I'm not advocating changing anything.

--
Daniel Gustafsson

Andres Freund <andres@anarazel.de> writes:
> On 2023-12-21 08:39:26 +0900, Michael Paquier wrote:
>> On Wed, Dec 20, 2023 at 11:36:28AM -0500, Tom Lane wrote:
>>> I thought the plan was to get rid of that file, in pursuit of making
>>> our distribution tarballs be more or less pure git pulls.  Instead of
>>> expending more effort on it, why not just push that project forward?

> Ah, right.  I don't really care what solution we go for, just that as long as
> we have INSTALL, we should make sure we don't regularly break it... Both
> Michael and I have in the last couple weeks.

So let's just do it.  I think the only real question is what URL
to point at exactly.  We can't simply say

https://www.postgresql.org/docs/current/installation.html

because that will be wrong for any version more than one major
release back.  We could make it version-specific,

https://www.postgresql.org/docs/17/installation.html

and task src/tools/version_stamp.pl with updating it.  But that's
problematic for not-yet-released branches (there's no 17 today
for example).  Perhaps we can use /devel/ in the master branch
and try to remember to replace that with a version number as soon
as a release branch is forked off --- but does the docs website
get populated as soon as the branch is made?

            regards, tom lane

Hi,

On 2023-12-21 10:22:49 -0500, Tom Lane wrote:
> I think the only real question is what URL to point at exactly.  We can't
> simply say
> 
> https://www.postgresql.org/docs/current/installation.html
> 
> because that will be wrong for any version more than one major
> release back.

Right.


> We could make it version-specific,
> 
> https://www.postgresql.org/docs/17/installation.html
> 
> and task src/tools/version_stamp.pl with updating it.  But that's
> problematic for not-yet-released branches (there's no 17 today
> for example).

Perhaps we could make the website redirect 17 to /devel/ until 17 is branched
off?


> Perhaps we can use /devel/ in the master branch
> and try to remember to replace that with a version number as soon
> as a release branch is forked off --- but does the docs website
> get populated as soon as the branch is made?

I think it runs a few times a day - breaking the link for a few hours wouldn't
be optimal, but also not the end of the world. But redirecting $vnext -> to
devel would probably be a more reliable approach.

Greetings,

Andres Freund

Andres Freund <andres@anarazel.de> writes:
> On 2023-12-21 10:22:49 -0500, Tom Lane wrote:
>> We could make it version-specific,
>> https://www.postgresql.org/docs/17/installation.html
>> and task src/tools/version_stamp.pl with updating it.  But that's
>> problematic for not-yet-released branches (there's no 17 today
>> for example).

> Perhaps we could make the website redirect 17 to /devel/ until 17 is branched
> off?

Hmm, maybe, but then there's a moving part in version-stamping that's not
accessible to the average committer.  On the other hand, it wouldn't
be too awful if that redirect didn't get updated instantly after a
branch.  This is probably a point where we need advice from the web
team about how they manage documentation branches on the site.

>> Perhaps we can use /devel/ in the master branch
>> and try to remember to replace that with a version number as soon
>> as a release branch is forked off --- but does the docs website
>> get populated as soon as the branch is made?

> I think it runs a few times a day - breaking the link for a few hours wouldn't
> be optimal, but also not the end of the world. But redirecting $vnext -> to
> devel would probably be a more reliable approach.

Let's go with "/devel/ in master and a number in release branches"
for now, and tweak that if the web team wants to take on maintaining
a redirect.  I'll put together a concrete patch proposal in a little
bit.

            regards, tom lane

Hi,

On 2023-12-21 10:46:02 -0500, Tom Lane wrote:
> Andres Freund <andres@anarazel.de> writes:
> > On 2023-12-21 10:22:49 -0500, Tom Lane wrote:
> >> We could make it version-specific,
> >> https://www.postgresql.org/docs/17/installation.html
> >> and task src/tools/version_stamp.pl with updating it.  But that's
> >> problematic for not-yet-released branches (there's no 17 today
> >> for example).
> 
> > Perhaps we could make the website redirect 17 to /devel/ until 17 is branched
> > off?
> 
> Hmm, maybe, but then there's a moving part in version-stamping that's not
> accessible to the average committer.  On the other hand, it wouldn't
> be too awful if that redirect didn't get updated instantly after a
> branch.  This is probably a point where we need advice from the web
> team about how they manage documentation branches on the site.

IIRC the relevant part of the website code has access to a table of
documentation versions, so the redirect could be implement based on not
knowing the version.


> >> Perhaps we can use /devel/ in the master branch
> >> and try to remember to replace that with a version number as soon
> >> as a release branch is forked off --- but does the docs website
> >> get populated as soon as the branch is made?
> 
> > I think it runs a few times a day - breaking the link for a few hours wouldn't
> > be optimal, but also not the end of the world. But redirecting $vnext -> to
> > devel would probably be a more reliable approach.
> 
> Let's go with "/devel/ in master and a number in release branches"
> for now, and tweak that if the web team wants to take on maintaining
> a redirect.  I'll put together a concrete patch proposal in a little
> bit.

Cool.

Greetings,

Andres Freund

Andres Freund <andres@anarazel.de> writes:
> On 2023-12-21 10:46:02 -0500, Tom Lane wrote:
>> Let's go with "/devel/ in master and a number in release branches"
>> for now, and tweak that if the web team wants to take on maintaining
>> a redirect.  I'll put together a concrete patch proposal in a little
>> bit.

> Cool.

Here's a draft patch for this.  Most of it is mechanical removal of
infrastructure for building the INSTALL file.  If anyone wants to
bikeshed on the new wording of README, feel free.

            regards, tom lane

diff --git a/GNUmakefile.in b/GNUmakefile.in
index 80db4c73f8..eba569e930 100644
--- a/GNUmakefile.in
+++ b/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)
diff --git a/Makefile b/Makefile
index c66fb3027b..9bc1a4ec17 100644
--- a/Makefile
+++ b/Makefile
@@ -17,13 +17,7 @@ all:

 all check install installdirs installcheck installcheck-parallel uninstall clean distclean maintainer-clean dist
distcheckworld 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
diff --git a/README b/README
index 56d0c951a9..e40e610ccb 100644
--- a/README
+++ b/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
diff --git a/README.git b/README.git
deleted file mode 100644
index 4bf614eea4..0000000000
--- a/README.git
+++ /dev/null
@@ -1,14 +0,0 @@
-(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:
-    https://www.postgresql.org/docs/devel/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
-needed when using a tarball, since the files they are needed to build are
-already present in the tarball.  (On Windows, however, you need Perl anyway.)
diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore
index 88a07d852e..91f2781fe7 100644
--- a/doc/src/sgml/.gitignore
+++ b/doc/src/sgml/.gitignore
@@ -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
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 2ef818900f..725fec59e7 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -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
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index c129215dd3..db4bcce56e 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -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>

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index e23c784aa5..bb55695300 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.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>
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index e1a85dc607..94ec2bda1c 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -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
 #
diff --git a/doc/src/sgml/standalone-install.xml b/doc/src/sgml/standalone-install.xml
deleted file mode 100644
index b29e90daf9..0000000000
--- a/doc/src/sgml/standalone-install.xml
+++ /dev/null
@@ -1,170 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<!--
-This file contains the stand-alone installation instructions that end up in
-the INSTALL file.  This document stitches together parts of the installation
-instructions in the main documentation with some material that only appears
-in the stand-alone version.
--->
-<article id="installation">
- <title><productname>PostgreSQL</productname> Installation from Source Code</title>
-
- <!-- This text replaces the introductory text of installation.sgml -->
- <para>
-  This document describes the installation of
-  <productname>PostgreSQL</productname> using this source code distribution.
- </para>
-
- <para>
-  If you are building <productname>PostgreSQL</productname> for Microsoft
-  Windows, read this document if you intend to build with MinGW or Cygwin;
-  but if you intend to build with Microsoft's <productname>Visual
-  C++</productname>, see the main documentation instead.
- </para>
-
- <xi:include href="postgres-full.xml" xpointer="install-requirements" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="postgres-full.xml" xpointer="install-make" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="postgres-full.xml" xpointer="install-post" xmlns:xi="http://www.w3.org/2001/XInclude"/>
-
- <sect1 id="install-getting-started">
-  <title>Getting Started</title>
-
-  <para>
-   The following is a quick summary of how to get <productname>PostgreSQL</productname> up and
-   running once installed. The main documentation contains more information.
-  </para>
-
-  <procedure>
-   <step>
-    <para>
-     Create a user account for the <productname>PostgreSQL</productname>
-     server. This is the user the server will run as. For production
-     use you should create a separate, unprivileged account
-     (<quote>postgres</quote> is commonly used). If you do not have root
-     access or just want to play around, your own user account is
-     enough, but running the server as root is a security risk and
-     will not work.
-<screen><userinput>adduser postgres</userinput></screen>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Create a database installation with the <command>initdb</command>
-     command. To run <command>initdb</command> you must be logged in to your
-     <productname>PostgreSQL</productname> server account. It will not work as
-     root.
-<screen>root# <userinput>mkdir /usr/local/pgsql/data</userinput>
-root# <userinput>chown postgres /usr/local/pgsql/data</userinput>
-root# <userinput>su - postgres</userinput>
-postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</userinput></screen>
-    </para>
-
-    <para>
-     The <option>-D</option> option specifies the location where the data
-     will be stored. You can use any path you want, it does not have
-     to be under the installation directory. Just make sure that the
-     server account can write to the directory (or create it, if it
-     doesn't already exist) before starting <command>initdb</command>, as
-     illustrated here.
-    </para>
-   </step>
-
-   <step>
-    <para>
-     At this point, if you did not use the <command>initdb</command> <literal>-A</literal>
-     option, you might want to modify <filename>pg_hba.conf</filename> to control
-     local access to the server before you start it.  The default is to
-     trust all local users.
-    </para>
-   </step>
-
-   <step>
-    <para>
-     The previous <command>initdb</command> step should have told you how to
-     start up the database server. Do so now. The command should look
-     something like:
-<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start</programlisting>
-    </para>
-
-    <para>
-     To stop a server running in the background you can type:
-<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data stop</programlisting>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Create a database:
-<screen><userinput>/usr/local/pgsql/bin/createdb testdb</userinput></screen>
-     Then enter:
-<screen><userinput>/usr/local/pgsql/bin/psql testdb</userinput></screen>
-     to connect to that database. At the prompt you can enter SQL
-     commands and start experimenting.
-    </para>
-   </step>
-  </procedure>
- </sect1>
-
- <sect1 id="install-whatnow">
-  <title>What Now?</title>
-
-  <para>
-   <itemizedlist>
-    <listitem>
-     <para>
-      The <productname>PostgreSQL</productname> distribution contains a
-      comprehensive documentation set, which you should read sometime.
-      After installation, the documentation can be accessed by
-      pointing your browser to
-      <filename>/usr/local/pgsql/doc/html/index.html</filename>, unless you
-      changed the installation directories.
-     </para>
-
-     <para>
-      The first few chapters of the main documentation are the Tutorial,
-      which should be your first reading if you are completely new to
-      <acronym>SQL</acronym> databases.  If you are familiar with database
-      concepts then you want to proceed with part on server
-      administration, which contains information about how to set up
-      the database server, database users, and authentication.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      Usually, you will want to modify your computer so that it will
-      automatically start the database server whenever it boots. Some
-      suggestions for this are in the documentation.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      Run the regression tests against the installed server (using
-      <command>make installcheck</command>). If you didn't run the
-      tests before installation, you should definitely do it now. This
-      is also explained in the documentation.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      By default, <productname>PostgreSQL</productname> is configured to run on
-      minimal hardware.  This allows it to start up with almost any
-      hardware configuration. The default configuration is, however,
-      not designed for optimum performance. To achieve optimum
-      performance, several server parameters must be adjusted, the two
-      most common being <varname>shared_buffers</varname> and
-      <varname>work_mem</varname>.
-      Other parameters mentioned in the documentation also affect
-      performance.
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
- </sect1>
-
- <xi:include href="postgres.sgml" xpointer="supported-platforms" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="postgres.sgml" xpointer="installation-platform-notes" xmlns:xi="http://www.w3.org/2001/XInclude"/>
-</article>
diff --git a/doc/src/sgml/standalone-profile.xsl b/doc/src/sgml/standalone-profile.xsl
deleted file mode 100644
index a2d78bc10d..0000000000
--- a/doc/src/sgml/standalone-profile.xsl
+++ /dev/null
@@ -1,97 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0">
-
-<!--
-This is a preprocessing layer to convert the installation instructions into a
-variant without links and references to the main documentation.
-
-- To omit something in the stand-alone INSTALL file, give the element a
-  condition="standalone-ignore" attribute.
-
-- If there is no element that exactly covers what you want to change, wrap it
-  in a <phrase> element, which otherwise does nothing.
-
-- Otherwise, write a custom rule below.
--->
-
-<xsl:output
-    doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
-    doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/>
-
-<!-- copy everything by default -->
-
-<xsl:template match="@*|node()">
-  <xsl:copy>
-    <xsl:apply-templates select="@*|node()" />
-  </xsl:copy>
-</xsl:template>
-
-<!-- particular conversions -->
-
-<xsl:template match="*[@condition='standalone-ignore']">
-</xsl:template>
-
-<xsl:template match="phrase/text()['chapter']">
-  <xsl:text>document</xsl:text>
-</xsl:template>
-
-<xsl:template match="phrase[@id='install-ldap-links']">
-  <xsl:text>the documentation about client authentication and libpq</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='collation']">
-  <xsl:text>the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='docguide-toolsets']">
-  <xsl:text>the main documentation's appendix on documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='dynamic-trace']">
-  <xsl:text>the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='install-meson']">
-  <xsl:text>the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='guc-default-toast-compression']">
-  <xsl:text>the configuration parameter default_toast_compression</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='guc-wal-compression']">
-  <xsl:text>the configuration parameter wal_compression</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='locale-providers']">
-  <xsl:text>the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='plpython-python23']">
-  <xsl:text>the </xsl:text><application>PL/Python</application><xsl:text> documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='regress']">
-  <xsl:text>the file </xsl:text>
-  <filename>src/test/regress/README</filename>
-  <xsl:text> and the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='upgrading']">
-  <xsl:text>the documentation</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='uuid-ossp']">
-  <xsl:text>uuid-ossp</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='xml2']">
-  <xsl:text>xml2</xsl:text>
-</xsl:template>
-
-<xsl:template match="xref[@linkend='sepgsql']">
-  <xsl:text>sepgsql</xsl:text>
-</xsl:template>
-
-</xsl:stylesheet>
diff --git a/src/pl/plperl/README b/src/pl/plperl/README
index e61dd57f53..bdf2dc05b0 100644
--- a/src/pl/plperl/README
+++ b/src/pl/plperl/README
@@ -6,5 +6,4 @@ To build from this directory use 'make all; make install'.  libperl
 must have been built as a shared library, which is usually not the
 case in standard installations.

-Consult the PostgreSQL User's Guide and the INSTALL file in the
-top-level directory of the source distribution for more information.
+Consult the PostgreSQL User's Guide for more information.
diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES
index 73b02fa2a4..0f30f85ec7 100644
--- a/src/tools/RELEASE_CHANGES
+++ b/src/tools/RELEASE_CHANGES
@@ -107,6 +107,9 @@ Starting a New Development Cycle
   placeholder), "git rm" the previous one, and update release.sgml and
   filelist.sgml to match.

+* In the newly-made branch, replace "devel" with the branch's major version
+  number in the URLs appearing in the top-level README and Makefile files.
+
 * In the newly-made branch, change src/backend/nodes/gen_node_support.pl
   to enforce ABI stability of the NodeTag list (see "ARM ABI STABILITY
   CHECK HERE" therein).

On Thu, Dec 21, 2023 at 02:22:02PM -0500, Tom Lane wrote:
> Here's a draft patch for this.  Most of it is mechanical removal of
> infrastructure for building the INSTALL file.  If anyone wants to
> bikeshed on the new wording of README, feel free.

Thanks for putting this together.  That looks reasonable.

> diff --git a/README b/README
> index 56d0c951a9..e40e610ccb 100644
> --- a/README
> +++ b/README
> @@ -9,14 +9,13 @@ that supports an extended subset of the SQL standard, including
> -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

Sounds fine by me, including the extra step documented in
RELEASE_CHANGES.  No information is lost.
--
Michael

Michael Paquier <michael@paquier.xyz> writes:
> On Thu, Dec 21, 2023 at 02:22:02PM -0500, Tom Lane wrote:
>> Here's a draft patch for this.  Most of it is mechanical removal of
>> infrastructure for building the INSTALL file.  If anyone wants to
>> bikeshed on the new wording of README, feel free.

> Thanks for putting this together.  That looks reasonable.

Thanks for checking it.  Pushed --- we can tweak things later
if we decide the web-redirect idea is superior to this.

            regards, tom lane