Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1pIxuN-0004x5-9F
	for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Jan 2023 20:22:43 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1pIxuL-0006QD-Gr
	for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Jan 2023 20:22:41 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <kop@karlpinc.com>)
	id 1pIxuL-0006PX-7L
	for pgsql-hackers@lists.postgresql.org; Fri, 20 Jan 2023 20:22:41 +0000
Received: from janus.karlpinc.com ([173.161.46.12] helo=smtp.karlpinc.com)
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <kop@karlpinc.com>)
	id 1pIxuG-0007O5-NY
	for pgsql-hackers@lists.postgresql.org; Fri, 20 Jan 2023 20:22:40 +0000
Received: from slate.karlpinc.com (unknown [192.168.1.14])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
	 key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest
 SHA256)
	(No client certificate requested)
	by smtp.karlpinc.com (Postfix) with ESMTPS id E6EF4A19B;
	Fri, 20 Jan 2023 14:22:32 -0600 (CST)
Received: from slate.karlpinc.com (localhost [IPv6:::1])
	by slate.karlpinc.com (Postfix) with ESMTPS id B28573FC11;
	Fri, 20 Jan 2023 14:22:32 -0600 (CST)
Date: Fri, 20 Jan 2023 14:22:25 -0600
From: "Karl O. Pinc" <kop@karlpinc.com>
To: Alvaro Herrera <alvherre@alvh.no-ip.org>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked
 sentences
Message-ID: <20230120142225.3d3be8a3@slate.karlpinc.com>
In-Reply-To: <20230120191238.ds5l4ehuxve4zn42@alvherre.pgsql>
References: <20230120191203.7nyqjbw3qe7xx4ru@alvherre.pgsql>
	<20230120191238.ds5l4ehuxve4zn42@alvherre.pgsql>
X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.33; x86_64-pc-linux-gnu)
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="MP_/CreK5aACK_8K0NDBPdE7+OR"
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Archived-At: 
 <https://www.postgresql.org/message-id/20230120142225.3d3be8a3%40slate.karlpinc.com>
Precedence: bulk

--MP_/CreK5aACK_8K0NDBPdE7+OR
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

On Fri, 20 Jan 2023 20:12:38 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> Ah, I wanted to attach the two remaining patches and forgot. 

Attached are 2 alternatives:
(They touch separate files so the ordering is meaningless.)


v8-0001-List-trusted-and-obsolete-extensions.patch

Instead of putting [trusted] and [obsolete] in the titles
of the modules, like v7 does, add a list of them into the text.


v8-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch

This frobs the PDF style sheet so that when sect1 is used
in the appendix for the contrib directory, there is a page
break before every sect1.  This puts each module/extension
onto a separate page, but only for the contrib appendix.

Aside from hardcoding the "contrib" id, which I suppose isn't
too bad since it's publicly exposed as a HTML anchor (or URL 
component?) and unlikely to change, this also means that the 
contrib documentation can't use <section> instead of <sect1>.

Sometimes I think I only know enough XSLT to get into trouble.
While v8 is "right", I can't say if it is a good idea/good practice.

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

--MP_/CreK5aACK_8K0NDBPdE7+OR
Content-Type: text/x-patch
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename=v8-0001-List-trusted-and-obsolete-extensions.patch

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 8816e06337..87833915e9 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -84,6 +84,31 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
   provide access to outside-the-database functionality.
  </para>
 
+ <para id="contrib-trusted-extensions">These are the trusted extensions:
+   <simplelist type="inline">
+     <member><xref linkend="btree-gin"/></member>
+     <member><xref linkend="btree-gist"/></member>
+     <member><xref linkend="citext"/></member>
+     <member><xref linkend="cube"/></member>
+     <member><xref linkend="dict-int"/></member>
+     <member><xref linkend="fuzzystrmatch"/></member>
+     <member><xref linkend="hstore"/></member>
+     <member><xref linkend="intarray"/></member>
+     <member><xref linkend="isn"/></member>
+     <member><xref linkend="lo"/></member>
+     <member><xref linkend="ltree"/></member>
+     <member><xref linkend="pgcrypto"/></member>
+     <member><xref linkend="pgtrgm"/></member>
+     <member><xref linkend="seg"/></member>
+     <member><xref linkend="tablefunc"/></member>
+     <member><xref linkend="tcn"/></member>
+     <member><xref linkend="tsm-system-rows"/></member>
+     <member><xref linkend="tsm-system-time"/></member>
+     <member><xref linkend="unaccent"/></member>
+     <member><xref linkend="uuid-ossp"/></member>
+   </simplelist>     
+ </para>
+
  <para>
   Many extensions allow you to install their objects in a schema of your
   choice.  To do that, add <literal>SCHEMA
@@ -100,6 +125,15 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
   component for details.
  </para>
 
+ <para id="contrib-obsolete">
+   These modules and extensions are obsolete:
+
+   <simplelist type="inline">
+     <member><xref linkend="intagg"/></member>
+     <member><xref linkend="xml2"/></member>
+   </simplelist>
+ </para>
+
  &adminpack;
  &amcheck;
  &auth-delay;

--MP_/CreK5aACK_8K0NDBPdE7+OR
Content-Type: text/x-patch
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename=v8-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch

diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 0c4dff92c4..68a46f9e24 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -132,4 +132,12 @@
   </fo:bookmark>
 </xsl:template>
 
+<!-- Every sect1 in the appendix describing contributed modules
+     gets a page break -->
+
+<xsl:template match="id('contrib')/sect1">
+  <fo:block break-after='page'/>
+  <xsl:apply-imports/>
+</xsl:template>
+
 </xsl:stylesheet>

--MP_/CreK5aACK_8K0NDBPdE7+OR--