Horton

Thread

Commits

  1. Remove new <para id="contrib-obsolete">.

  2. doc/PDF: Add page breaks for <sect1> in contrib appendix

  3. doc: Add lists of modules trusted/obsolete

  4. HTML docs: Add padding to table.simplelist for more readable output

  5. Describe each contrib module in its SGML section title

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-03T00:00:15Z

    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.

I added the word "extension" into the appendix title
because I always have problems scanning through the
appendix and finding the one to do with extensions.

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.

Regards,

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

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

    Brar Piening <brar@gmx.de> — 2023-01-15T06:11:30Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-15T13:35:21Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-18T12:25:57Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-18T12:30:45Z

    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)

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-18T15:50:12Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-18T17:34:47Z

    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)

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-18T19:01:18Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-18T19:06:05Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-19T12:35:17Z

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-19T17:03:53Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-19T18:02:05Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-20T11:42:31Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-20T12:26:00Z

    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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-20T19:12:03Z

    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"

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-01-20T19:12:38Z

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

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-20T19:33:46Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-20T20:22:25Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-20T20:54:38Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-21T14:11:43Z

    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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-22T14:09:03Z

    On Sat, 21 Jan 2023 08:11:43 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

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

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-22T20:42:46Z

    On Sun, 22 Jan 2023 08:09:03 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

> On Sat, 21 Jan 2023 08:11:43 -0600
> "Karl O. Pinc" <kop@karlpinc.com> wrote:
> 
> > 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.  
> 
> Come to think of it, this should be fixed by using CSS
> with a
> 
>   table.simplelist

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-01-22T21:29:41Z

    On Sun, 22 Jan 2023 14:42:46 -0600
"Karl O. Pinc" <kop@karlpinc.com> wrote:

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

In theory, a number of other simplelist presentations
could benefit from this.  For example, in the Data Types
Boolean Type section the true truth values are
presently listed vertically, like so:

true
yes
on
1

Instead they could still be listed 'type="vert"' (the default),
but with 'columns="4"', to produce something like:

  true    yes    on    1

This stands out just as much, but takes less space
on the page.

Likewise, perhaps some tables are tables instead of
simplelists just because putting simplelists into
columns was so ugly.

I'll leave such modifications to others, at least for
now.

Regards,

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-09T09:22:49Z

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

> 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; }

Okay, this looks good to me too.  However, for it to actually work, we
need to patch the corresponding CSS file in the pgweb repository too.
I'll follow up in the other mailing list.

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-09T09:27:28Z

    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:

> 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 */
> 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.

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

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

    Daniel Gustafsson <daniel@yesql.se> — 2023-03-09T09:35:18Z

    > On 9 Mar 2023, at 10:27, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> ... but in addition it needs the pgweb CSS to be updated to match, as in
> the attached patch.
> 
> What do you think?

LGTM.

--
Daniel Gustafsson

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

    Jonathan S. Katz <jkatz@postgresql.org> — 2023-03-09T17:34:05Z

    On 3/9/23 4:35 AM, Daniel Gustafsson wrote:
>> On 9 Mar 2023, at 10:27, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
> 
>> ... but in addition it needs the pgweb CSS to be updated to match, as in
>> the attached patch.
>>
>> What do you think?
> 
> LGTM.

I'm OK with the change, I'm not OK with the comment around it because 
"Simplelist" doesn't really give meaning to it AFAICT. Maybe:

/** Additional formatting for "simplelist" structures */
#docContent table.simplelist td {
	padding-left: 2em;
	padding-right: 2em;
}

Jonathan

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-09T18:36:47Z

    On 2023-Mar-09, Jonathan S. Katz wrote:

> I'm OK with the change, I'm not OK with the comment around it because
> "Simplelist" doesn't really give meaning to it AFAICT. Maybe:
> 
> /** Additional formatting for "simplelist" structures */
> #docContent table.simplelist td {
> 	padding-left: 2em;
> 	padding-right: 2em;
> }

Uh, absolutely.  Here's a complete patch (in case you wanted that),
thanks.

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"Las cosas son buenas o malas segun las hace nuestra opinión" (Lisias)

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-11T22:31:28Z

    Hi Alvaro,

On Thu, 9 Mar 2023 10:22:49 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Jan-22, Karl O. Pinc wrote:
> 
> > Actually, this CSS, added to doc/src/sgml/stylesheet.css,
> > makes the column spacing look pretty good:
> Okay, this looks good to me too.  However, for it to actually work, we
> need to patch the corresponding CSS file in the pgweb repository too.
> I'll follow up in the other mailing list.

Do you also like the page breaking in the PDF for each
contributed package, per the
v10-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch
of
https://www.postgresql.org/message-id/20230122144246.0ff87372%40slate.karlpinc.com
?

No need to reply if I don't need to do anything.  (I didn't
want the patch to get lost.)

Thanks for the review.

Regards,

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

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

    Jonathan S. Katz <jkatz@postgresql.org> — 2023-03-13T13:26:45Z

    On 3/9/23 1:36 PM, Alvaro Herrera wrote:
> On 2023-Mar-09, Jonathan S. Katz wrote:
> 
>> I'm OK with the change, I'm not OK with the comment around it because
>> "Simplelist" doesn't really give meaning to it AFAICT. Maybe:
>>
>> /** Additional formatting for "simplelist" structures */
>> #docContent table.simplelist td {
>> 	padding-left: 2em;
>> 	padding-right: 2em;
>> }
> 
> Uh, absolutely.  Here's a complete patch (in case you wanted that),
> thanks.

LGTM -- pushed. If it's not reflected within a few hours please let me 
know and I'll force clear the caches.

Thanks,

Jonathan

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

    Gregory Stark (as CFM) <stark.cfm@gmail.com> — 2023-03-14T17:49:23Z

    On Mon, 13 Mar 2023 at 09:28, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> > Uh, absolutely.  Here's a complete patch (in case you wanted that),
> > thanks.
>
> LGTM -- pushed. If it's not reflected within a few hours please let me
> know and I'll force clear the caches.

I think this means the patch is committed? I'll update the commitfest
entry as committed but if there's more to be done feel free to fix.

-- 
Gregory Stark
As Commitfest Manager

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

    Greg Stark <stark@mit.edu> — 2023-03-14T17:51:36Z

    On Tue, 14 Mar 2023 at 13:49, Gregory Stark (as CFM)
<stark.cfm@gmail.com> wrote:
>
> On Mon, 13 Mar 2023 at 09:28, Jonathan S. Katz <jkatz@postgresql.org> wrote:
> >
> > > Uh, absolutely.  Here's a complete patch (in case you wanted that),
> > > thanks.
> >
> > LGTM -- pushed. If it's not reflected within a few hours please let me
> > know and I'll force clear the caches.
>
> I think this means the patch is committed? I'll update the commitfest
> entry as committed but if there's more to be done feel free to fix.

Hum. Jonathon Katz isn't listed as a committer -- is this a web site
change or something else? Or do we need to add Jonathon?

-- 
greg

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

    Greg Stark <stark@mit.edu> — 2023-03-14T17:57:57Z

    Sorry, having read the whole thread I think it's clear. The source
tree patch was committed by Alvaro H in
a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
pgweb change. So I gather this is resolved now and I've marked it
committed by Alvaro.

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-14T21:29:19Z

    On Tue, 14 Mar 2023 13:57:57 -0400
Greg Stark <stark@mit.edu> wrote:

> Sorry, having read the whole thread I think it's clear. The source
> tree patch was committed by Alvaro H in
> a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
> pgweb change. So I gather this is resolved now and I've marked it
> committed by Alvaro.

There remains an un-committed patch from this thread/commitfest
entry:
v10-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch

When generating the PDF docs it starts each contrib entry on
a separate page.

From:
https://www.postgresql.org/message-id/20230122144246.0ff87372%40slate.karlpinc.com

I've re-attached the patch.  Nobody has commented directly
on this particular patch, although there was a "looks ok" reply 
to the email.

I don't know what the policy is now that the commitfest entry
is closed.  Perhaps Alvaro was planning on committing it?

Please let me know if I should open up a new
commitfest entry or if there is something else I need to do.

Thanks for the help.

Regards,

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-15T08:41:27Z

    On 2023-Mar-14, Karl O. Pinc wrote:

> On Tue, 14 Mar 2023 13:57:57 -0400
> Greg Stark <stark@mit.edu> wrote:
> 
> > Sorry, having read the whole thread I think it's clear. The source
> > tree patch was committed by Alvaro H in
> > a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
> > pgweb change. So I gather this is resolved now and I've marked it
> > committed by Alvaro.

Actually, the 0001 patch hadn't been fully committed yet ... I had only
added the CSS tweaks.  I have now pushed the addition of the tables to
the SGML sources, with minor tag changes: I found that with the
<simplelist> outside of any <para>, the list was too close to the next
paragraph, which looked a bit ugly.  I put the list inside the <para>
that explains what the list is.  It looks good with PDF, website-HTML
and plain-HTML rendering now; didn't look at other output formats.
So, the CF entry being marked committed is now correct as far as I'm
concerned.

> There remains an un-committed patch from this thread/commitfest
> entry:

> 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

> +<!-- Every sect1 in the contrib appendix gets a page break -->
> +<xsl:template match="id('contrib')/sect1">
> +  <fo:block break-after='page'/>
> +  <xsl:apply-imports/>
> +</xsl:template>

Yeah, I think this one achieves what I wanted and isn't a maintenance
burden, but I would like to hear from other CSS people.  I guess I could
just commit it and see what complaints I get (probably none).

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
“Cuando no hay humildad las personas se degradan” (A. Christie)

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-15T13:55:21Z

    On Wed, 15 Mar 2023 09:41:27 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> Actually, the 0001 patch hadn't been fully committed yet ... I had
> only added the CSS tweaks.  I have now pushed the addition of the
> tables to the SGML sources, with minor tag changes: I found that with
> the <simplelist> outside of any <para>, the list was too close to the
> next paragraph, which looked a bit ugly.  I put the list inside the
> <para> that explains what the list is.  It looks good with PDF,
> website-HTML and plain-HTML rendering now; didn't look at other
> output formats. So, the CF entry being marked committed is now
> correct as far as I'm concerned.

Thanks for noticing that.  (I'd always vaguely wondered about
lists being inside v.s. outside of paragraphs.  There must be other
places in the docs where this matters.  ?)

> > There remains an un-committed patch from this thread/commitfest
> > entry:  
> 
> > 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  
> 
> > +<!-- Every sect1 in the contrib appendix gets a page break -->
> > +<xsl:template match="id('contrib')/sect1">
> > +  <fo:block break-after='page'/>
> > +  <xsl:apply-imports/>
> > +</xsl:template>  
> 
> Yeah, I think this one achieves what I wanted and isn't a maintenance
> burden, but I would like to hear from other CSS people.  I guess I
> could just commit it and see what complaints I get (probably none).

FWIW, this patch is not to CSS.  It's XSLT and affects only the PDF
generation.

(The patch is a response to your "aside" and remarks regarding a
separate thread, here:
https://www.postgresql.org/message-id/20230118173447.aegjdk3girgkqu2g%40alvherre.pgsql
)

Regards,

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-20T13:16:45Z

    On 2023-Mar-15, Karl O. Pinc wrote:

> On Wed, 15 Mar 2023 09:41:27 +0100
> Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> > Yeah, I think this one achieves what I wanted and isn't a maintenance
> > burden, but I would like to hear from other CSS people.  I guess I
> > could just commit it and see what complaints I get (probably none).
> 
> FWIW, this patch is not to CSS.  It's XSLT and affects only the PDF
> generation.

Yeah, I misspoke.  I was aware it's XSLT, a territory I'm wholly
unfamiliar with.  I have pushed it now nonetheless.  Thank you!

> (The patch is a response to your "aside" and remarks regarding a
> separate thread, here:
> https://www.postgresql.org/message-id/20230118173447.aegjdk3girgkqu2g%40alvherre.pgsql
> )

Right :-)

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
"El destino baraja y nosotros jugamos" (A. Schopenhauer)

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-20T17:32:19Z

    On Mon, 20 Mar 2023 14:16:45 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Mar-15, Karl O. Pinc wrote:

> Yeah, I misspoke.  I was aware it's XSLT, a territory I'm wholly
> unfamiliar with.  I have pushed it now nonetheless.  Thank you!

Thank you for all your help with this.

Regards,

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-20T20:20:38Z

    Hi,

There seems to be a problem with the html generated
for the public-facing Postgresql docs.

I'm looking at the contrib page in the devel docs,
on the pg website:

https://www.postgresql.org/docs/devel/contrib.html

The simplelist holding the list of trusted extensions,
in doc/src/sgml/contrib.sgml, is inside the paragraph.

But when I look at the delivered html, I see the table
outside of the paragraph.  And the vertical spacing
looks poor as a result.

Alvaro moved the simplelist into the paragraph to
fix just this problem.

Building HEAD (of master) on my computer (Debian 11.6)
what I see is the generation of two paragraphs,
one with the leading text and a second that contains
the simplelist table.  (Er, why 2 paragraphs instead
of just one paragraph with both text and table in
it I can't say.)

The html built on my computer has vertical spacing
that looks good.

Could it be that the build system has out-of-date
docbook xslt?  In any case, it looks like what's
produced for the world to see is different from what
Alvaro and I are seeing.

Regards,

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

P.S.  I don't know what html Alvero is generating,
but his looks good and what's on postgresql.org does
not look good.  So I assume that he's getting something
different from what the public sees now.

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-23T03:23:38Z

    Hi,

I rebuilt the HEAD (master) html with:

  make STYLE=website html

and what I see locally is still different from
what is on postgresql.org. 

So the build system does indeed seem to be generating
"different html" that looks un-good compared to what
Alvaro and I are seeing when we build locally.


On Mon, 20 Mar 2023 15:20:38 -0500
"Karl O. Pinc" <kop@karlpinc.com> wrote:

> There seems to be a problem with the html generated
> for the public-facing Postgresql docs.
> 
> I'm looking at the contrib page in the devel docs,
> on the pg website:
> 
> https://www.postgresql.org/docs/devel/contrib.html
> 
> The simplelist holding the list of trusted extensions,
> in doc/src/sgml/contrib.sgml, is inside the paragraph.
> 
> But when I look at the delivered html, I see the table
> outside of the paragraph.  And the vertical spacing
> looks poor as a result.
> 
> Alvaro moved the simplelist into the paragraph to
> fix just this problem.
> 
> Building HEAD (of master) on my computer (Debian 11.6)
> what I see is the generation of two paragraphs,
> one with the leading text and a second that contains
> the simplelist table.  (Er, why 2 paragraphs instead
> of just one paragraph with both text and table in
> it I can't say.)
> 
> The html built on my computer has vertical spacing
> that looks good.
> 
> Could it be that the build system has out-of-date
> docbook xslt?  In any case, it looks like what's
> produced for the world to see is different from what
> Alvaro and I are seeing.
> 
> Regards,
> 
> Karl <kop@karlpinc.com>
> Free Software:  "You don't pay back, you pay forward."
>                  -- Robert A. Heinlein
> 
> P.S.  I don't know what html Alvero is generating,
> but his looks good and what's on postgresql.org does
> not look good.  So I assume that he's getting something
> different from what the public sees now.


Regards,

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-03-23T09:45:51Z

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

> Hi,
> 
> I rebuilt the HEAD (master) html with:
> 
>   make STYLE=website html
> 
> and what I see locally is still different from
> what is on postgresql.org. 
> 
> So the build system does indeed seem to be generating
> "different html" that looks un-good compared to what
> Alvaro and I are seeing when we build locally.

Hah, you're right -- the website is missing the closing </p>.  Weird.
It is definitely possible that the website is using outdated XSLT
stylesheets.  For example, at the top of the page in my local build I
see this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>

whereas the website only says

<!doctype html>
<html lang="en">
 <head>

I don't to waste time investigating that, though.  

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-29T17:07:38Z

    Is this the pgsql-www list the right place to report
this so it does not get forgotten?  (If so, no need to reply.)

On Thu, 23 Mar 2023 10:45:51 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Mar-22, Karl O. Pinc wrote:

> > I rebuilt the HEAD (master) html with:
> > 
> >   make STYLE=website html
> > 
> > and what I see locally is still different from
> > what is on postgresql.org. 
> > 
> > So the build system does indeed seem to be generating
> > "different html" that looks un-good compared to what
> > Alvaro and I are seeing when we build locally.  
> 
> Hah, you're right -- the website is missing the closing </p>.  Weird.
> It is definitely possible that the website is using outdated XSLT
> stylesheets.
<snip>

Regards,

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

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

    Jonathan S. Katz <jkatz@postgresql.org> — 2023-03-29T17:17:33Z

    On 3/23/23 5:45 AM, Alvaro Herrera wrote:
> On 2023-Mar-22, Karl O. Pinc wrote:
> 
>> Hi,
>>
>> I rebuilt the HEAD (master) html with:
>>
>>    make STYLE=website html
>>
>> and what I see locally is still different from
>> what is on postgresql.org.
>>
>> So the build system does indeed seem to be generating
>> "different html" that looks un-good compared to what
>> Alvaro and I are seeing when we build locally.
> 
> Hah, you're right -- the website is missing the closing </p>.  Weird.
> It is definitely possible that the website is using outdated XSLT
> stylesheets.  For example, at the top of the page in my local build I
> see this:
> 
> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>
> 
> whereas the website only says
> 
> <!doctype html>
> <html lang="en">
>   <head>

The above doctype correct for the web. That's the HTML5 doctype tag.

I haven't gone through the the doc loading process in awhile, but what 
happens is that the docs build with the HTML generated (make html) and 
then are processed and "uploaded" to the website through this code[1]. 
It's possible that somewhere in the "HTML tidy" process something may be 
removed.

Looking at the current state of the contrib page, I'm not sure what the 
rendering is that you expect. I can see us adding more margin to the 
bottom of the table as that looks close together, but I'm not sure I 
understand what other issues there are?

Jonathan

[1] 
https://git.postgresql.org/gitweb/?p=pgweb.git;a=blob;f=tools/docs/docload.py;hb=HEAD

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-29T18:23:33Z

    On Wed, 29 Mar 2023 13:17:33 -0400
"Jonathan S. Katz" <jkatz@postgresql.org> wrote:

> The above doctype correct for the web. That's the HTML5 doctype tag.

That might be the difference, since (IIRC) the locally built site
is xhtml.  Which does not seem right -- I'd expect them to be
the same.  Otherwise doc patch developers can't tell what
they are producing.

> Looking at the current state of the contrib page, I'm not sure what
> the rendering is that you expect. I can see us adding more margin to
> the bottom of the table as that looks close together, but I'm not
> sure I understand what other issues there are?

That's pretty much the issue.  The visual presentation differs
between the public pages and my locally generated pages.
Underlying this is a difference in the generated html,
the "real" issue IMO.

But first, a summary:

At the bottom of
https://www.postgresql.org/docs/devel/contrib.html
there is the text: "The following extensions are trusted
in a default installation:"  After this there is a table.

On the public site the bottom of the table is "too close" to
the top of the next paragraph.  Not so when locally building
the html.

The difference, when I look using browser-based web development
tools, is that the locally generated table is in a paragraph
but on the public page the table is not.


This accounts for the difference in presentation, which was
a deliberate choice in the docbook source sgml.  The simplelist
element was moved inside the para element to produce a "standard"
vertical spacing between it and the next paragraph.

I suppose that even though the docbook DTD allows a simplelist
in a para there's no guarantee that whether one does so matters?
And/or maybe there's no guarantee that the presentation is the
same when generating xhtml v.s. html5?  (This would seem wrong
to me, but I suppose there could be reasons.)  Or there could be
a bug in one or the other set of html-producing style sheets.

I see that in html5 the table element is allowed only in flow
context, not phrasing context.  So maybe tables can't be put
into paragraphs?  I'd still think that the html5 stylesheets could
wrap tables that are "supposed to be" in paragraphs in div
elements with a class that allows them to be styled like
html5 p tags.  (Perhaps this is the "fix"??  Or just throw
an empty paragraph after such tables to sidestep CSS?)

So there may be a problem somewhere in the html generation.

In any case, isn't it a problem that html5 is produced for
public consumption and xhtml produced when independently generating
the docs?

Sorry to run-on.  Thinking out loud.

Regards,

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

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

    Noah Misch <noah@leadboat.com> — 2023-03-30T04:32:05Z

    On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote:
> v10-0001-List-trusted-and-obsolete-extensions.patch

> + <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>

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

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

    Karl O. Pinc <kop@karlpinc.com> — 2023-03-30T06:27:05Z

    On Wed, 29 Mar 2023 21:32:05 -0700
Noah Misch <noah@leadboat.com> wrote:

> On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote:
> > v10-0001-List-trusted-and-obsolete-extensions.patch  
> 
> > + <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>  
> 
> 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 <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

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

    Noah Misch <noah@leadboat.com> — 2023-04-09T18:50:50Z

    On Thu, Mar 30, 2023 at 01:27:05AM -0500, Karl O. Pinc wrote:
> On Wed, 29 Mar 2023 21:32:05 -0700
> Noah Misch <noah@leadboat.com> wrote:
> 
> > On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote:
> > > v10-0001-List-trusted-and-obsolete-extensions.patch  
> > 
> > > + <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>  
> > 
> > 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.

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

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

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-04-09T18:52:34Z

    On 2023-Apr-09, Noah Misch wrote:

> On Thu, Mar 30, 2023 at 01:27:05AM -0500, Karl O. Pinc wrote:

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

I agree, let's just remove that.  The list of trusted modules is clearly
useful, but the list of obsoletes one isn't terribly interesting.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"El miedo atento y previsor es la madre de la seguridad" (E. Burke)