Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences

From: "Karl O. Pinc" <[email-masked]>
Date: Fri, 20 Jan 2023 14:22:25 -0600

On Fri, 20 Jan 2023 20:12:38 +0100
Alvaro Herrera <[email-masked]> 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 <[email-masked]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein
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;
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>

---

From: "Karl O. Pinc" <[email-masked]>
Date: Sat, 21 Jan 2023 08:11:43 -0600

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

> 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.)

> 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 <[email-masked]>
index 0c4dff92c4..9ce36c7279 100644
 
+<!-- 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>
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 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>
 
+   <simplelist type="vert" columns="5">

---

From: "Karl O. Pinc" <[email-masked]>
Date: Sun, 22 Jan 2023 08:09:03 -0600

On Sat, 21 Jan 2023 08:11:43 -0600

> do more work on the stylesheets, but this seems excessive.

Come to think of it, this should be fixed by using CSS
with a

  table.simplelist

selector.  Or something along those lines.  But I don't
have a serious interest in proceeding further.  A inline
list seems good enough, even if it does not stand out
in a visual scan of the page.  There is a certain amount
of visual-standout due to all the hyperlinks next to each
other in the inline presentation.

Regards,

Karl <[email-masked]>

---

From: "Karl O. Pinc" <[email-masked]>
Date: Sun, 22 Jan 2023 14:42:46 -0600

On Sun, 22 Jan 2023 08:09:03 -0600

> Come to think of it, this should be fixed by using CSS

Actually, this CSS, added to doc/src/sgml/stylesheet.css,
makes the column spacing look pretty good:

/* Adequate spacing between columns in a simplelist non-inline table */
.simplelist td { padding-left: 2em; padding-right: 2em; }

(No point in specifying table, since td only shows up in tables.)

Note that the default simplelist type value is "vert", causing a 1
column vertical display.  There are a number of these in the
documenation. I kind of like what the above css does to these
layouts.  An example would be the layout in
doc/src/sgml/html/datatype-boolean.html, which is the "Data Types"
section "Boolean Type" sub-section.

For other places affected see: grep -l doc/src/sgml/*.sgml simplelist

Attached are 2 patches:

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

List trusted extenions in 4 columns, with the CSS altered
to put spacing between vertical columns.  I changed this
from the 5 columns of v9 because with 5 columns there
was a little bit of overflow into the right hand margin
of a US-letter PDF.  The PDF still has an ugly page
break right before the table.  To avoid that use the v8
version, which presents the list inline.

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

This is exactly like the v8 version.  See my comments earlier
about v8 v.s. v9.

Regards,

Karl <[email-masked]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 12c79b798b..b9f3268cad 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -84,6 +84,32 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
   provide access to outside-the-database functionality.
  </para>
 
+ <simplelist type="vert" columns="4">
@@ -100,6 +126,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;
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 6410a47958..61d8a6537d 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -163,3 +163,6 @@ acronym		{ font-style: inherit; }
     width: 75%;
   }
 }
+
+/* Adequate spacing between columns in a simplelist non-inline table */
+table.simplelist td { padding-left: 2em; padding-right: 2em; }
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>

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 9 Mar 2023 10:27:28 +0100

Hello pgsql-web,

We're looking to improve the contrib docs with a list of trusted
extensions.  In order for that look more presentable, Karl has come up
with the idea of using a <simplelist> table with multiple columns.  That
would normally look quite terrible because the cell contents are too
close to one another, so he came up with the idea of increasing the
padding, as shown in this patch.

I think this is good thing, as it can help us use tabular <simplelist>
in other places too.

This change requires to change main Postgres doc/src/sgml/stylesheet.css 
as Karl suggested here:

On 2023-Jan-22, Karl O. Pinc wrote:

> table.simplelist td { padding-left: 2em; padding-right: 2em; }
> 

... but in addition it needs the pgweb CSS to be updated to match, as in
the attached patch.

What do you think?

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"The eagle never lost so much time, as
when he submitted to learn of the crow." (William Blake)
>From bb4a5388cbc373789c7548a4a390e37bbab8dbec Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <[email-masked]>
Date: Thu, 9 Mar 2023 10:22:23 +0100
Subject: [PATCH] Add padding to table.simplelist for more readable output

Suggested by Karl Pinc
---
 media/css/main.css | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/media/css/main.css b/media/css/main.css
index 723366c9..fd082ae4 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -1169,6 +1169,12 @@ code,
   color: var(--doccontent-code-fg-color) !important;
 }
 
+/** Simplelist */
+#docContent table.simplelist td {
+	padding-left: 2em;
+	padding-right: 2em;
+}
+
 /**
   * Various callout boxes for docs, including warning, caution, note, tip
   */
-- 
2.30.2

---

From: Noah Misch <[email-masked]>
Date: Wed, 29 Mar 2023 21:32:05 -0700

> +     <member><xref linkend="xml2"/></member>

Commit a013738 incorporated this change.  Since xml2 is the only in-tree way
to use XSLT from SQL, I think xml2 is not obsolete.  Some individual
functions, e.g. xml_valid(), are obsolete.  (There are years-old threats to
render the module obsolete, but this has never happened.)

---

From: "Karl O. Pinc" <[email-masked]>
Date: Thu, 30 Mar 2023 01:27:05 -0500

On Wed, 29 Mar 2023 21:32:05 -0700
Noah Misch <[email-masked]> wrote:

> Commit a013738 incorporated this change.  Since xml2 is the only
> in-tree way to use XSLT from SQL, I think xml2 is not obsolete.  Some
> individual functions, e.g. xml_valid(), are obsolete.  (There are
> years-old threats to render the module obsolete, but this has never
> happened.)

Your point seems valid but this is above my station.
I have no idea as to how to best resolve this, or even how to make the
resolution happen now that the change has been committed.
Someone who knows more than me about the situation is needed
to change the phrasing, or re-categorize, or rework the xml2
module docs, or come up with new categories of obsolescence-like 
states, or provide access to libxslt from PG, or something.

I am invested in the patch and appreciate being cc-ed.

Regards,

Karl <[email-masked]>

---

From: Noah Misch <[email-masked]>
Date: Sun, 9 Apr 2023 11:50:50 -0700

> resolution happen now that the change has been committed.

I'm inclined to just remove <para id="contrib-obsolete">.  While intagg is
indeed obsolete, having a one-entry list seems like undue weight.