Thread: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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
Attachment
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
Attachment
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/)
Attachment
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
Attachment
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
Attachment
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/
Attachment
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
Attachment
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
Attachment
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
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
Attachment
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
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/
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
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.)
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
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.
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)