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
Date: Sat, 21 Jan 2023 08:11:43 -0600
Message-ID: <20230121081143.322bcf9f@slate.karlpinc.com> (raw)
In-Reply-To: <20230120142225.3d3be8a3@slate.karlpinc.com>
References: <20230120191203.7nyqjbw3qe7xx4ru@alvherre.pgsql>
<20230120191238.ds5l4ehuxve4zn42@alvherre.pgsql>
<20230120142225.3d3be8a3@slate.karlpinc.com>
Attached are 2 v9 patch versions. I don't think I like them.
I think the v8 versions are better. But I thought it
wouldn't hurt to show them to you.
On Fri, 20 Jan 2023 14:22:25 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:
> 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.
v9 puts the list in vertical format, 5 columns.
But the column spacing in HTML is ugly, and I don't
see a parameter to set to change it. I suppose we could
do more work on the stylesheets, but this seems excessive.
It looks good in PDF, but the page break in the middle
of the paragraph is ugly. (US-Letter) Again (without forcing a hard
page break by frobbing the stylesheet and adding a processing
instruction), I don't see a a good way to fix the page break.
(sagehill.net says that soft page breaks don't work. I didn't
try it.)
> 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>.
v9 supports using <section> instead of just <sect1>. But
I don't know that it's worth it -- the appendix is committed
to sect* entities. Once you start with sect* the stylesheet
does not allow "section" use to be interspersed. All the
sect*s would have to be changed to "section" throughout
the appendix and I don't see that happening.
Regards,
Karl <kop@karlpinc.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
Attachments:download all (2 files, .tar.gz)v9-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch (text/x-patch, 501B) downloaddiff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xslindex 0c4dff92c4..9ce36c7279 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|id('contrib')/section">+ <fo:block break-after='page'/>+ <xsl:apply-imports/>+</xsl:template>+
</xsl:stylesheet>
v9-0001-List-trusted-and-obsolete-extensions.patch (text/x-patch, 1.9K) downloaddiff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgmlindex 12c79b798b..077184d90d 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="vert" columns="5">+ <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;
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-www@postgresql.org
Cc: kop@karlpinc.com, alvherre@alvh.no-ip.org, pgsql-hackers@lists.postgresql.org
Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
In-Reply-To: <20230121081143.322bcf9f@slate.karlpinc.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox