Get rid of parameterized marked sections in SGML

Previously, we created a variant of the installation instructions for
producing the plain-text INSTALL file by marking up certain parts of
installation.sgml using SGML parameterized marked sections.  Marked
sections will not work anymore in XML, so before we can convert the
documentation to XML, we need a new approach.

DocBook provides a "profiling" feature that allows selecting content
based on attributes, which would work here.  But it imposes a noticeable
overhead when building the full documentation and causes complications
when building some output formats, and given that we recently spent a
fair amount of effort optimizing the documentation build time, it seems
sad to have to accept that.

So as an alternative, (1) we create our own mini-profiling layer that
adjusts just the text we want, and (2) assemble the pieces of content
that we want in the INSTALL file using XInclude.  That way, there is no
overhead when building the full documentation and most of the "ugly"
stuff in installation.sgml can be removed and dealt with out of line.

doc/src/sgml/Makefile

@@ -134,9 +134,8 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml
 	$(XMLLINT) --noout --valid $*.xml
 	$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@
 
-INSTALL.xml: standalone-install.sgml installation.sgml version.sgml
+INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.xml
-	$(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $(filter-out version.sgml,$^) >$@.tmp
+	$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@
-	$(call mangle-xml,chapter)
 
 
 ##

doc/src/sgml/filelist.sgml

@@ -190,12 +190,3 @@
 
 <!-- back matter -->
 <!ENTITY biblio     SYSTEM "biblio.sgml">
-
-<!--
- Some parts of the documentation are also source for some plain-text
- files used during installation.  To selectively ignore or include
- some parts (e.g., external xref's) when generating these files we use
- these parameter entities.  See also standalone-install.sgml.
- -->
-<!ENTITY % standalone-ignore  "INCLUDE">
-<!ENTITY % standalone-include "IGNORE">

doc/src/sgml/installation.sgml

@@ -1,28 +1,25 @@
 <!-- doc/src/sgml/installation.sgml -->
 <!--
 
-Use </link> not just </> so INSTALL.html can be created without links
+The standalone version has some portions that are different from the version
-to the main documentation.  Don't use <xref>; or if you must, wrap it
+that is integrated into the full documentation set, in particular as regards
-in a standalone-ignore clause.
+links, so that INSTALL.html can be created without links to the main
+documentation.  See standalone-profile.xsl for details.
 
 -->
 
 <chapter id="installation">
- <title><![%standalone-include[<productname>PostgreSQL</>]]>
+ <title>Installation from Source Code</title>
-  Installation from Source Code</title>
 
  <indexterm zone="installation">
   <primary>installation</primary>
  </indexterm>
 
  <para>
-  This <![%standalone-include;[document]]>
+  This chapter describes the installation of
-  <![%standalone-ignore;[chapter]]> describes the installation of
   <productname>PostgreSQL</productname> using the source code
   distribution.  (If you are installing a pre-packaged distribution,
-  such as an RPM or Debian package, ignore this
+  such as an RPM or Debian package, ignore this chapter
-  <![%standalone-include;[document]]>
-  <![%standalone-ignore;[chapter]]>
   and read the packager's instructions instead.)
  </para>
 
@@ -45,8 +42,7 @@ su - postgres
 /usr/local/pgsql/bin/psql test
 </synopsis>
    The long version is the rest of this
-   <![%standalone-include;[document.]]>
+   <phrase>chapter</phrase>.
-   <![%standalone-ignore;[chapter.]]>
   </para>
  </sect1>
 
@@ -197,8 +193,7 @@ su - postgres
       required version is <productname>Python</productname> 2.4.
       <productname>Python 3</productname> is supported if it's
       version 3.1 or later; but see
-      <![%standalone-include[the <application>PL/Python</> documentation]]>
+      <xref linkend="plpython-python23">
-      <![%standalone-ignore[<xref linkend="plpython-python23">]]>
       when using Python 3.
      </para>
 
@@ -267,9 +262,7 @@ su - postgres
      <para>
       To build the <productname>PostgreSQL</productname> documentation,
       there is a separate set of requirements; see
-      <![%standalone-ignore;[<xref linkend="docguide-toolsets">.]]>
+      <xref linkend="docguide-toolsets">.
-      <![%standalone-include;[the main documentation's appendix on
-      documentation.]]>
      </para>
     </listitem>
    </itemizedlist>
@@ -340,7 +333,6 @@ su - postgres
   </para>
  </sect1>
 
-<![%standalone-ignore;[
  <sect1 id="install-getsource">
   <title>Getting The Source</title>
 
@@ -369,7 +361,6 @@ su - postgres
    <xref linkend="sourcerepo">.
   </para>
  </sect1>
-]]>
 
  <sect1 id="install-procedure">
   <title>Installation Procedure</title>
@@ -844,9 +835,8 @@ su - postgres
         <para>
          Build with <acronym>LDAP</><indexterm><primary>LDAP</></>
          support for authentication and connection parameter lookup (see
-         <![%standalone-include[the documentation about client authentication
+         <phrase id="install-ldap-links"><xref linkend="libpq-ldap"> and
-         and libpq]]><![%standalone-ignore[<xref linkend="libpq-ldap"> and
+         <xref linkend="auth-ldap"></phrase> for more information). On Unix,
-         <xref linkend="auth-ldap">]]> for more information). On Unix,
          this requires the <productname>OpenLDAP</> package to be
          installed. On Windows, the default <productname>WinLDAP</>
          library is used.  <filename>configure</> will check for the required
@@ -865,8 +855,8 @@ su - postgres
          for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
          service notifications.  This improves integration if the server binary
          is started under <application>systemd</application> but has no impact
-         otherwise<![%standalone-ignore[; see <xref linkend="server-start"> for more
+         otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"> for more
-         information]]>.  <application>libsystemd</application> and the
+         information</phrase>.  <application>libsystemd</application> and the
          associated header files need to be installed to be able to use this
          option.
         </para>
@@ -911,8 +901,7 @@ su - postgres
        <term><option>--with-uuid=<replaceable>LIBRARY</replaceable></option></term>
        <listitem>
         <para>
-         Build the <![%standalone-include[uuid-ossp]]>
+         Build the <xref linkend="uuid-ossp"> module
-         <![%standalone-ignore[<xref linkend="uuid-ossp">]]> module
          (which provides functions to generate UUIDs), using the specified
          UUID library.<indexterm><primary>UUID</primary></indexterm>
          <replaceable>LIBRARY</replaceable> must be one of:
@@ -979,8 +968,7 @@ su - postgres
        <listitem>
         <para>
          Use libxslt when building the
-         <![%standalone-include[xml2]]>
+         <xref linkend="xml2">
-         <![%standalone-ignore[<xref linkend="xml2">]]>
          module.  <application>xml2</> relies on this library
          to perform XSL transformations of XML.
         </para>
@@ -1096,8 +1084,7 @@ su - postgres
          has no support for strong random numbers on the platform.
          A source of random numbers is needed for some authentication
          protocols, as well as some routines in the
-         <![%standalone-include[pgcrypto]]>
+         <xref linkend="pgcrypto">
-         <![%standalone-ignore[<xref linkend="pgcrypto">]]>
          module. <option>--disable-strong-random</option> disables functionality that
          requires cryptographically strong random numbers, and substitutes
          a weak pseudo-random-number-generator for the generation of
@@ -1201,8 +1188,8 @@ su - postgres
          code coverage testing instrumentation.  When run, they
          generate files in the build directory with code coverage
          metrics.
-         <![%standalone-ignore[See <xref linkend="regress-coverage">
+         <phrase condition="standalone-ignore">See <xref linkend="regress-coverage">
-         for more information.]]> This option is for use only with GCC
+         for more information.</phrase> This option is for use only with GCC
          and when doing development work.
         </para>
        </listitem>
@@ -1262,8 +1249,8 @@ su - postgres
          </indexterm>
          Compiles <productname>PostgreSQL</productname> with support for the
          dynamic tracing tool DTrace.
-         <![%standalone-ignore[See <xref linkend="dynamic-trace">
+         <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace">
-         for more information.]]>
+         for more information.</phrase>
         </para>
 
         <para>
@@ -1298,7 +1285,7 @@ su - postgres
         <para>
          Enable tests using the Perl TAP tools.  This requires a Perl
          installation and the Perl module <literal>IPC::Run</literal>.
-         <![%standalone-ignore;[See <xref linkend="regress-tap"> for more information.]]>
+         <phrase condition="standalone-ignore">See <xref linkend="regress-tap"> for more information.</phrase>
         </para>
        </listitem>
       </varlistentry>
@@ -1455,9 +1442,7 @@ su - postgres
          whether Python 2 or 3 is specified here (or otherwise
          implicitly chosen) determines which variant of the PL/Python
          language becomes available.  See
-         <![%standalone-include[the <application>PL/Python</>
+         <xref linkend="plpython-python23">
-         documentation]]>
-         <![%standalone-ignore[<xref linkend="plpython-python23">]]>
          for more information.
         </para>
        </listitem>
@@ -1584,10 +1569,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install.
 <userinput>make check</userinput>
 </screen>
     (This won't work as root; do it as an unprivileged user.)
-    <![%standalone-include[The file
+    See <xref linkend="regress"> for
-    <filename>src/test/regress/README</> and the
-    documentation contain]]>
-    <![%standalone-ignore[<xref linkend="regress"> contains]]>
     detailed information about interpreting the test results. You can
     repeat this test at any later time by issuing the same command.
    </para>
@@ -1599,8 +1581,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install.
    <note>
     <para>
      If you are upgrading an existing system be sure to read
-     <![%standalone-include[the documentation,]]>
+     <xref linkend="upgrading">,
-     <![%standalone-ignore[<xref linkend="upgrading">]]>
      which has instructions about upgrading a
      cluster.
     </para>
@@ -1858,167 +1839,6 @@ export MANPATH
   </sect2>
  </sect1>
 
-
-<![%standalone-include;[
- <sect1 id="install-getting-started">
-  <title>Getting Started</title>
-
-  <para>
-   The following is a quick summary of how to get <productname>PostgreSQL</> up and
-   running once installed. The main documentation contains more information.
-  </para>
-
-  <procedure>
-   <step>
-    <para>
-     Create a user account for the <productname>PostgreSQL</>
-     server. This is the user the server will run as. For production
-     use you should create a separate, unprivileged account
-     (<quote>postgres</> 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</>
-</screen>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Create a database installation with the <command>initdb</>
-     command. To run <command>initdb</> you must be logged in to your
-     <productname>PostgreSQL</> server account. It will not work as
-     root.
-<screen>
-root# <userinput>mkdir /usr/local/pgsql/data</>
-root# <userinput>chown postgres /usr/local/pgsql/data</>
-root# <userinput>su - postgres</>
-postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
-</screen>
-    </para>
-
-    <para>
-     The <option>-D</> 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</>, as
-     illustrated here.
-    </para>
-   </step>
-
-   <step>
-    <para>
-     At this point, if you did not use the <command>initdb</> <literal>-A</>
-     option, you might want to modify <filename>pg_hba.conf</> 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</> 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/postgres -D /usr/local/pgsql/data
-</programlisting>
-     This will start the server in the foreground. To put the server
-     in the background use something like:
-<programlisting>
-nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
-    &lt;/dev/null &gt;&gt;server.log 2&gt;&amp;1 &lt;/dev/null &amp;
-</programlisting>
-    </para>
-
-    <para>
-     To stop a server running in the background you can type:
-<programlisting>
-kill `cat /usr/local/pgsql/data/postmaster.pid`
-</programlisting>
-    </para>
-   </step>
-
-   <step>
-    <para>
-     Create a database:
-<screen>
-<userinput>createdb testdb</>
-</screen>
-     Then enter:
-<screen>
-<userinput>psql testdb</>
-</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</> 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</>, 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</> 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</> 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>
-]]>
-
-
  <sect1 id="supported-platforms">
   <title>Supported Platforms</title>
 
@@ -2076,9 +1896,7 @@ kill `cat /usr/local/pgsql/data/postmaster.pid`
    regarding the installation and setup of PostgreSQL.  Be sure to
    read the installation instructions, and in
    particular <xref linkend="install-requirements"> as well.  Also,
-   check <![%standalone-include[the
+   check <xref linkend="regress"> regarding the
-   file <filename>src/test/regress/README</> and the documentation]]>
-   <![%standalone-ignore[<xref linkend="regress">]]> regarding the
    interpretation of regression test results.
   </para>
 
@@ -2429,7 +2247,7 @@ ERROR:  could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address
    <para>
     PostgreSQL can be built using Cygwin, a Linux-like environment for
     Windows, but that method is inferior to the native Windows build
-    <![%standalone-ignore[(see <xref linkend="install-windows">)]]> and
+    <phrase condition="standalone-ignore">(see <xref linkend="install-windows">)</phrase> and
     running a server under Cygwin is no longer recommended.
    </para>
 
@@ -2623,8 +2441,7 @@ PHSS_30849  s700_800 u2comp/be/plugin library Patch
     Microsoft's <productname>Visual C++</productname> compiler suite.
     The MinGW build variant uses the normal build system described in
     this chapter; the Visual C++ build works completely differently
-    and is described in <![%standalone-include[the
+    and is described in <xref linkend="install-windows">.
-    documentation]]><![%standalone-ignore[<xref linkend="install-windows">]]>.
     It is a fully native build and uses no additional software like
     MinGW.  A ready-made installer is available on the main
     PostgreSQL web site.
@@ -2785,10 +2602,8 @@ LIBOBJS = snprintf.o
     <title>Using DTrace for Tracing PostgreSQL</title>
 
     <para>
-     Yes, using DTrace is possible.  See <![%standalone-include[the
+     Yes, using DTrace is possible.  See <xref linkend="dynamic-trace"> for
-     documentation]]>
+     further information.
-     <![%standalone-ignore[<xref linkend="dynamic-trace">]]> for further
-     information.
     </para>
 
     <para>

doc/src/sgml/standalone-install.sgml

@@ -1,28 +0,0 @@
-<!-- doc/src/sgml/standalone-install.sgml -->
-
-<!--
-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" [
-
-<!ENTITY % version SYSTEM "version.sgml">
-%version;
-
-<!--
-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. The following are essentially SGML's
-equivalent of C's #ifdef and friends. The other end of this is in
-installation.sgml.
--->
-
- <!ENTITY % standalone-ignore  "IGNORE">
- <!ENTITY % standalone-include "INCLUDE">
-
-<!--
-When you're building the full documentation set, you want to flip the
-IGNORE and INCLUDE.
--->
-]>

doc/src/sgml/standalone-install.xml

@@ -0,0 +1,167 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/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>
+
+ <para>
+  This document describes the installation of
+  <productname>PostgreSQL</productname> using this source code distribution.
+ </para>
+
+ <xi:include href="postgres.xml" xpointer="install-short" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="postgres.xml" xpointer="install-requirements" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="postgres.xml" xpointer="install-procedure" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="postgres.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/postgres -D /usr/local/pgsql/data</programlisting>
+     This will start the server in the foreground. To put the server
+     in the background use something like:
+<programlisting>nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
+    &lt;/dev/null &gt;&gt;server.log 2&gt;&amp;1 &lt;/dev/null &amp;</programlisting>
+    </para>
+
+    <para>
+     To stop a server running in the background you can type:
+<programlisting>kill `cat /usr/local/pgsql/data/postmaster.pid`</programlisting>
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Create a database:
+<screen><userinput>createdb testdb</userinput></screen>
+     Then enter:
+<screen><userinput>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.xml" xpointer="supported-platforms" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="postgres.xml" xpointer="installation-platform-notes" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</article>

doc/src/sgml/standalone-profile.xsl

@@ -0,0 +1,81 @@
+<?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.2//EN"
+    doctype-system="http://www.oasis-open.org/docbook/xml/4.2/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='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-windows']">
+  <xsl:text>the documentation</xsl:text>
+</xsl:template>
+
+<xsl:template match="xref[@linkend='pgcrypto']">
+  <xsl:text>pgcrypto</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:stylesheet>