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

On 03.01.2023 at 01:00, Karl O. Pinc wrote:

Attached is a patch: contrib_v1.patch

It modifies Appendix F, the contrib directory.

Review:

The patch applies cleanly (1334b79a35 - 2023-01-14 18:05:09 +0900).

It adds a brief explanatory part to the headers of all contrib modules
which I consider as very useful, especially when looking at the TOC in
contrib.html where currently newcomers would need to click through all
the links to even get an idea what the various modules do.
The explanatory parts added make sense to me, althogh I'm not an expert
in all the different contrib modules.

Appendix F. now reads as "Additional Supplied Modules and Extensions"
instead of "Appendix F. Additional Supplied Modules" which IMHO proprely
reflects what it is about. The original title probably comes from the
pre-extension-era.

There is also some minor rewording of sentences in contrib.sgml that in
general looks like an improvment to me.

In conclusion I cannot see why this patch should not be applied in it's
current form so I deem it ready for commiter.

Regards,
Brar

On Sun, 15 Jan 2023 07:11:30 +0100
Brar Piening <brar@gmx.de> wrote:

On 03.01.2023 at 01:00, Karl O. Pinc wrote:

Attached is a patch: contrib_v1.patch

It modifies Appendix F, the contrib directory.

Review:

It adds a brief explanatory part to the headers of all contrib modules

The explanatory parts added make sense to me, althogh I'm not an
expert in all the different contrib modules.

Neither am I. I read the beginning of each module's docs and
made a best-effort. There may sometimes be a better
summary phrase to describe a module/extension.

Thanks for the review.

Regards,

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

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

Hi,

Attached is a patch: contrib_v1.patch

It modifies Appendix F, the contrib directory.

It adds brief text into the titles shown in the
table of contents so it's easier to tell what
each module does. It also suffixes [trusted] or [obsolete]
on the relevant titles.

This looks a good idea to me. I'm not 100% sold on having the "trusted"
or "obsolete" marker on the titles themselves, though. Not sure what
alternative do we have, though, other than leave them out completely.

There's a typo "equalivent" in two places.

In passwordcheck, I would say just "check for weak passwords" or maybe
"verify password strength".

pg_buffercache is missing. Maybe "-- inspect state of the Postgres
buffer cache".

For pg_stat_statements I suggest "track statistics of planning and
execution of SQL queries"

For sepgsql, as I understand it is strictly SELinux based, not just
"-like". So this needs rewording: "label-based, SELinux-like, mandatory
access control". Maybe "SELinux-based implementation of mandatory
access control for row-level security".

xml -- typo "qeurying"

The sentences describing what the modules are and how
to build them have been reworked. Some split in 2,
some words removed or replaced, etc.

I introduced the word "component" because the appendix
has build instructions for command line programs as well
as extensions and libraries loaded with shared_preload_libraries().
This involved removing most occurrences of the word
"module", although it is left in the section title.

I haven't read this part yet.

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"But static content is just dynamic content that isn't moving!"
http://smylers.hates-software.com/2007/08/15/fe244d0c.html

Not related to this patch: it's very annoying that in the PDF output,
each section in the appendix doesn't start on a blank page -- which
means that the doc page for many modules starts in the middle of a page
were the previous one ends. This is very ugly. And then you get to
dblink, which contains a bunch of reference pages for the functions it
provides, and those *do* start a new page each. So it looks quite
inconsistent.

I wonder if we can tweak something in the stylesheet to include a page
break.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"The Postgresql hackers have what I call a "NASA space shot" mentality.
Quite refreshing in a world of "weekend drag racer" developers."
(Scott Marlowe)

On Wed, 18 Jan 2023 13:30:45 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

Not related to this patch: it's very annoying that in the PDF output,
each section in the appendix doesn't start on a blank page -- which
means that the doc page for many modules starts in the middle of a
page were the previous one ends.

<snip>

I wonder if we can tweak something in the stylesheet to include a page
break.

Would this be something to be included in this patch?
(If I can figure it out.)

Regards,

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

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

On Wed, 18 Jan 2023 13:30:45 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

Not related to this patch: it's very annoying that in the PDF output,
each section in the appendix doesn't start on a blank page -- which
means that the doc page for many modules starts in the middle of a
page were the previous one ends.

<snip>

I wonder if we can tweak something in the stylesheet to include a page
break.

Would this be something to be included in this patch?
(If I can figure it out.)

No, I think we should do that change separately. I just didn't think a
parenthical complain was worth a separate thread for it; but if you do
create a patch, please do create a new thread (unless the current patch
in this one is committed already.)

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"Ninguna manada de bestias tiene una voz tan horrible como la humana" (Orual)

On Wed, 18 Jan 2023 13:25:57 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

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

Attached is a patch: contrib_v1.patch

It modifies Appendix F, the contrib directory.

It adds brief text into the titles shown in the
table of contents so it's easier to tell what
each module does. It also suffixes [trusted] or [obsolete]
on the relevant titles.

<snip>
I'm not 100% sold on having the
"trusted" or "obsolete" marker on the titles themselves, though. Not
sure what alternative do we have, though, other than leave them out
completely.

The alternative would be to have a separate table with modules
for rows and "trusted" and "obsolete" columns. It seems like
more of a maintenance hassle than having the markers in the titles.

Let me know if you want a table. I do like having a place
to look to over all the modules to see what is "trusted" or "obsolete".

I suppose there could just be a table, with module names, descriptions,
and trusted and obsolete flags. Instead of a table of contents
for the modules the module names in the table could be links. But
that'd involve suppressing the table of contents showing all the
module names. And has the problem of possible mis-match between
the modules listed in the table and the modules that exist.

There's a typo "equalivent" in two places.

Fixed.

In passwordcheck, I would say just "check for weak passwords" or maybe
"verify password strength".

I used "verify password strength".

pg_buffercache is missing. Maybe "-- inspect state of the Postgres
buffer cache".

I used "inspect Postgres buffer cache state"

For pg_stat_statements I suggest "track statistics of planning and
execution of SQL queries"

I had written "track SQL query planning and execution statistics".
Changed to: "track statistics of SQL planning and execution"

I don't really care. If you want your version I'll submit another
patch.

For sepgsql, as I understand it is strictly SELinux based, not just
"-like". So this needs rewording: "label-based, SELinux-like,
mandatory access control". Maybe "SELinux-based implementation of
mandatory access control for row-level security".

Changed to: "SELinux-based row-level security mandatory access control"

xml -- typo "qeurying"

Fixed.

I have also made the patch put each module on a separate
page when producing PDF documents. This did produce one warning,
which seems unrelated to me. The pdf seems right. I also tried
just "make", to be sure I didn't break anything unrelated. Seemed
to work. So..., works for me.

New patch attached: contrib_v2.patch

Regards,

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

On Wed, 18 Jan 2023 18:34:47 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

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

On Wed, 18 Jan 2023 13:30:45 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

Not related to this patch: it's very annoying that in the PDF
output, each section in the appendix doesn't start on a blank
page -- which means that the doc page for many modules starts in
the middle of a page were the previous one ends.

<snip>

I wonder if we can tweak something in the stylesheet to include a
page break.

Would this be something to be included in this patch?
(If I can figure it out.)

No, I think we should do that change separately. I just didn't think
a parenthical complain was worth a separate thread for it; but if you
do create a patch, please do create a new thread (unless the current
patch in this one is committed already.)

Oops. Already sent a revised patch that includes starting each
module on a new page, for PDF output. I'll wait to rip that
out after review and start a new thread if necessary.

Regards,

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

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

Oops. Already sent a revised patch that includes starting each
module on a new page, for PDF output. I'll wait to rip that
out after review and start a new thread if necessary.

Here's my review in the form of a delta patch.

I didn't find that a thing called "ISN" actually exists. Is there a
reference to that?

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
"How strange it is to find the words "Perl" and "saner" in such close
proximity, with no apparent sense of irony. I doubt that Larry himself
could have managed it." (ncm, http://lwn.net/Articles/174769/)

On Thu, 19 Jan 2023 13:35:17 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

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

Oops. Already sent a revised patch that includes starting each
module on a new page, for PDF output. I'll wait to rip that
out after review and start a new thread if necessary.

(I have not removed the PDF page breaks from the latest patch.)

Here's my review in the form of a delta patch.

Love it.

I didn't find that a thing called "ISN" actually exists. Is there a
reference to that?

Maybe. I came across it somewhere and it seemed useful. It's
an initialism for International Standard Number.
https://en.wikipedia.org/wiki/International_Standard_Number
It's the same ISN as in the file name, "isn.sgml".

I've frobbed the ISN related text in my response patch.
(And added a line break to btree-gin.)

Attached are 2 patches, a regular and a delta from your v4 review:

contrib_v5-delta.patch.txt
contrib_v5.patch.txt

Regards,

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

On Thu, 19 Jan 2023 11:03:53 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

Attached are 2 patches, a regular and a delta from your v4 review:

contrib_v5-delta.patch.txt
contrib_v5.patch.txt

I left your appendix title unchanged: "Additional Supplied
Extensions and Modules".

I had put "Extensions" after
"Modules", because, apparently, things that come last in the
sentence are most remembered by the reader. My impression is that
more people are looking for extensions than modules.

Regards,

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

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

On Thu, 19 Jan 2023 11:03:53 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

Attached are 2 patches, a regular and a delta from your v4 review:

contrib_v5-delta.patch.txt
contrib_v5.patch.txt

I left your appendix title unchanged: "Additional Supplied
Extensions and Modules".

I had put "Extensions" after
"Modules", because, apparently, things that come last in the
sentence are most remembered by the reader. My impression is that
more people are looking for extensions than modules.

Hmm, I didn't know that. I guess I can put it back. My own instinct is
to put the most important stuff first, not last, but if research says to
do otherwise, fine, let's do that.

I went over all the titles again. There were a couple of mistakes
and inconsistencies, which I've fixed to the best of my knowledge.
I'm happy with 0001 now and will push shortly unless there are
complaints.

I'm still unsure of the [trusted]/[obsolete] marker, so I split that out
to commit 0002. I would like to see more support for that before
pushing that one.

I also put the page-split bits to another page, because it seems a bit
too clumsy. I hope somebody with more docbook-fu can comment: maybe
there's a way to fix it more generally somehow?

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"Update: super-fast reaction on the Postgres bugs mailing list. The report
was acknowledged [...], and a fix is under discussion.
The wonders of open-source !"
https://twitter.com/gunnarmorling/status/1596080409259003906

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

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

On Thu, 19 Jan 2023 11:03:53 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

Attached are 2 patches, a regular and a delta from your v4 review:

contrib_v5-delta.patch.txt
contrib_v5.patch.txt

I left your appendix title unchanged: "Additional Supplied
Extensions and Modules".

I had put "Extensions" after
"Modules", because, apparently, things that come last in the
sentence are most remembered by the reader. My impression is that
more people are looking for extensions than modules.

Hmm, I didn't know that. I guess I can put it back. My own instinct
is to put the most important stuff first, not last, but if research
says to do otherwise, fine, let's do that.

A quick google on the subject tells me that I can't figure out a good
quick google. I believe it's from the book at bottom. Memorability
goes "end", "beginning", "middle". IIRC.

I went over all the titles again. There were a couple of mistakes
and inconsistencies, which I've fixed to the best of my knowledge.
I'm happy with 0001 now and will push shortly unless there are
complaints.

I'm still unsure of the [trusted]/[obsolete] marker, so I split that
out to commit 0002. I would like to see more support for that before
pushing that one.

I also put the page-split bits to another page, because it seems a bit
too clumsy.

All the above sounds good to me.

I hope somebody with more docbook-fu can comment: maybe
there's a way to fix it more generally somehow?

What would the general solution be? There could be a forced page
break at the beginning of _every_ sect1. For PDFs. That seems
a bit much, but maybe not. The only other thing I can think of
that's "general" would be to force a page break for sect1-s
that are in an appendix. Is any of this wanted? (Or technically
"better"?)

Thanks for the help.

----

Writing for Readers
By George R. Bramer, Dorothy Sedley · 1981

About this edition
ISBN:9780675080453, 0675080452
Page count:532
Published:1981
Format:Hardcover
Publisher:C.E. Merrill Publishing Company
Original from:Pennsylvania State University
Digitized:July 15, 2009
Language:English
Author:George R. Bramer, Dorothy Sedley

It's part of a wave of reaction against Strunk & White,
where they started basing writing on research into reading.
(If it's the right book.)

Regards,

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

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

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

Hmm, I didn't know that. I guess I can put it back. My own instinct
is to put the most important stuff first, not last, but if research
says to do otherwise, fine, let's do that.

A quick google on the subject tells me that I can't figure out a good
quick google. I believe it's from the book at bottom. Memorability
goes "end", "beginning", "middle". IIRC.

Ah well. I just put it back the way you had it.

I hope somebody with more docbook-fu can comment: maybe
there's a way to fix it more generally somehow?

What would the general solution be?

I don't know, I was thinking that perhaps at the start of the appendix
we could have some kind of marker that says "in this chapter, the
<sect1>s all get a page break", then a marker to stop that at the end of
the appendix. Or a tweak to the stylesheet, "when inside an appendix,
all <sect1>s get a pagebreak", in a way that doesn't affect the other
chapters.

The <?hard-pagebreak?> solution looks really ugly to me (in the source
code I mean), but I suppose if we discover no other way to do it, we
could do it like that.

There could be a forced page break at the beginning of _every_ sect1.
That seems a bit much, but maybe not. The only other thing I can
think of that's "general" would be to force a page break for sect1-s
that are in an appendix. Is any of this wanted? (Or technically
"better"?)

I wouldn't want to changing the behavior of all the <sect1>s in the
whole documentation. Though if you want to try and garner support to do
that, I won't oppose it, particularly since it only matters for PDF.

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
<inflex> really, I see PHP as like a strange amalgamation of C, Perl, Shell
<crab> inflex: you know that "amalgam" means "mixture with mercury",
more or less, right?
<crab> i.e., "deadly poison"

Ah, I wanted to attach the two remaining patches and forgot. Here they
are.

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/

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

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

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

Hmm, I didn't know that. I guess I can put it back. My own
instinct is to put the most important stuff first, not last, but
if research says to do otherwise, fine, let's do that.

A quick google on the subject tells me that I can't figure out a
good quick google. I believe it's from the book at bottom.
Memorability goes "end", "beginning", "middle". IIRC.

Ah well. I just put it back the way you had it.

I hope somebody with more docbook-fu can comment: maybe
there's a way to fix it more generally somehow?

What would the general solution be?

I don't know, I was thinking that perhaps at the start of the appendix
we could have some kind of marker that says "in this chapter, the
<sect1>s all get a page break", then a marker to stop that at the end
of the appendix. Or a tweak to the stylesheet, "when inside an
appendix, all <sect1>s get a pagebreak", in a way that doesn't affect
the other chapters.

The <?hard-pagebreak?> solution looks really ugly to me (in the source
code I mean), but I suppose if we discover no other way to do it, we
could do it like that.

I can do a forced page break for sect1-s in the pdf stylesheet just
for the contrib appendix (appendix F) by looking for a parent
with an id of "contrib". That would work, but seems like a kludge.
(Otherwise, you look for a parent of "appendix" and force the page
break in all appendixes.)

I'll send a patch.

Regards,

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

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

On Fri, 20 Jan 2023 14:22:25 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

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.

The list is inline. It might be worthwhile experimenting
with a tabular list, like that produced by:

<simplelist type="vert" columns="4">

But only for the list of trusted extensions. There's not
enough obsolete extensions to do anything but inline. (IMO)

Regards,

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

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