Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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 . 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)
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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 wrote: > > > On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote: > > > v10-0001-List-trusted-and-obsolete-extensions.patch > > > > > + > > > + These modules and extensions are obsolete: > > > + > > > + > > > + > > > + > > > + > > > + > > > > 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 . While intagg is indeed obsolete, having a one-entry list seems like undue weight.
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Wed, 29 Mar 2023 21:32:05 -0700 Noah Misch wrote: > On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote: > > v10-0001-List-trusted-and-obsolete-extensions.patch > > > + > > + These modules and extensions are obsolete: > > + > > + > > + > > + > > + > > + > > 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Sun, Jan 22, 2023 at 02:42:46PM -0600, Karl O. Pinc wrote: > v10-0001-List-trusted-and-obsolete-extensions.patch > + > + These modules and extensions are obsolete: > + > + > + > + > + > + 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.)
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
Hi Alvaro, On Thu, 9 Mar 2023 10:22:49 +0100 Alvaro Herrera 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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 HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Sun, 22 Jan 2023 14:42:46 -0600 "Karl O. Pinc" 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: trueyeson1 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Sun, 22 Jan 2023 08:09:03 -0600
"Karl O. Pinc" wrote:
> On Sat, 21 Jan 2023 08:11:43 -0600
> "Karl O. Pinc" 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" 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
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 12c79b798b..b9f3268cad 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -84,6 +84,32 @@ CREATE EXTENSION extension_name;
provide access to outside-the-database functionality.
+ These are the trusted extensions:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Many extensions allow you to install their objects in a schema of your
choice. To do that, add SCHEMA
@@ -100,6 +126,15 @@ CREATE EXTENSION extension_name;
component for details.
+
+ These modules and extensions are obsolete:
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 6410a47958..61d8a6537d 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -163,3 +163,6 @@ acronym { font-style: inherit; }
width: 75%;
}
}
+
+/* Adequate spacing between columns in a simplelist non-inline table */
+table.simplelist td { padding-left: 2em; padding-right: 2em; }
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 0c4dff92c4..68a46f9e24 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -132,4 +132,12 @@
+
+
+
+
+
+
+
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Sat, 21 Jan 2023 08:11:43 -0600 "Karl O. Pinc" 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" 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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" 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 instead of . v9 supports using instead of just . 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl index 0c4dff92c4..9ce36c7279 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -132,4 +132,12 @@ + + + + + + + diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 12c79b798b..077184d90d 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -84,6 +84,31 @@ CREATE EXTENSION extension_name; provide access to outside-the-database functionality. + These are the trusted extensions: + + + + + + + + + + + + + + + + + + + + + + + + Many extensions allow you to install their objects in a schema of your choice. To do that, add SCHEMA @@ -100,6 +125,15 @@ CREATE EXTENSION extension_name; component for details. + + These modules and extensions are obsolete: + + + + + + +
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Fri, 20 Jan 2023 14:22:25 -0600 "Karl O. Pinc" 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: But only for the list of trusted extensions. There's not enough obsolete extensions to do anything but inline. (IMO) Regards, Karl Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Fri, 20 Jan 2023 20:12:38 +0100 Alvaro Herrera 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 instead of . 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 8816e06337..87833915e9 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -84,6 +84,31 @@ CREATE EXTENSION extension_name; provide access to outside-the-database functionality. + These are the trusted extensions: + + + + + + + + + + + + + + + + + + + + + + + + Many extensions allow you to install their objects in a schema of your choice. To do that, add SCHEMA @@ -100,6 +125,15 @@ CREATE EXTENSION extension_name; component for details. + + These modules and extensions are obsolete: + + + + + + + diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl index 0c4dff92c4..68a46f9e24 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -132,4 +132,12 @@ + + + + + + +
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Fri, 20 Jan 2023 20:12:03 +0100 Alvaro Herrera wrote: > On 2023-Jan-20, Karl O. Pinc wrote: > > > On Fri, 20 Jan 2023 12:42:31 +0100 > > Alvaro Herrera 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 > 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 s get a pagebreak", in a way that doesn't affect > the other chapters. > > The 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
Ah, I wanted to attach the two remaining patches and forgot. Here they are. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ >From ba972984da37b5a315bd7a4face064d24ca41436 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Fri, 20 Jan 2023 12:32:22 +0100 Subject: [PATCH v7 1/2] Install [trusted] and [obsolete] markers in section title I'm not sure about this part. --- doc/src/sgml/btree-gin.sgml | 2 +- doc/src/sgml/btree-gist.sgml | 2 +- doc/src/sgml/citext.sgml | 2 +- doc/src/sgml/cube.sgml| 2 +- doc/src/sgml/dict-int.sgml| 2 +- doc/src/sgml/fuzzystrmatch.sgml | 2 +- doc/src/sgml/hstore.sgml | 2 +- doc/src/sgml/intagg.sgml | 2 +- doc/src/sgml/intarray.sgml| 2 +- doc/src/sgml/isn.sgml | 2 +- doc/src/sgml/lo.sgml | 2 +- doc/src/sgml/ltree.sgml | 2 +- doc/src/sgml/pgcrypto.sgml| 2 +- doc/src/sgml/pgtrgm.sgml | 2 +- doc/src/sgml/seg.sgml | 2 +- doc/src/sgml/tablefunc.sgml | 2 +- doc/src/sgml/tcn.sgml | 2 +- doc/src/sgml/tsm-system-rows.sgml | 2 +- doc/src/sgml/tsm-system-time.sgml | 2 +- doc/src/sgml/unaccent.sgml| 2 +- doc/src/sgml/uuid-ossp.sgml | 2 +- doc/src/sgml/xml2.sgml| 2 +- 22 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 46117209ce..db96f02ba9 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,7 +1,7 @@ - btree_gin GIN operator classes with B-tree behavior + btree_gin GIN operator classes with B-tree behavior [trusted] btree_gin diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index 31e7c78aae..be14779a92 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -1,7 +1,7 @@ - btree_gist GiST operator classes with B-tree behavior + btree_gist GiST operator classes with B-tree behavior [trusted] btree_gist diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml index 8322885661..ff8a98c21b 100644 --- a/doc/src/sgml/citext.sgml +++ b/doc/src/sgml/citext.sgml @@ -1,7 +1,7 @@ - citext a case-insensitive character string type + citext a case-insensitive character string type [trusted] citext diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 0fb7080748..1998e6d81a 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -1,7 +1,7 @@ - cube a multi-dimensional cube data type + cube a multi-dimensional cube data type [trusted] cube (extension) diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml index 8dd07b9bc1..293ba83ce6 100644 --- a/doc/src/sgml/dict-int.sgml +++ b/doc/src/sgml/dict-int.sgml @@ -2,7 +2,7 @@ dict_int - example full-text search dictionary for integers + example full-text search dictionary for integers [trusted] dict_int diff --git a/doc/src/sgml/fuzzystrmatch.sgml b/doc/src/sgml/fuzzystrmatch.sgml index 1a5ebbb22f..bf1caab54d 100644 --- a/doc/src/sgml/fuzzystrmatch.sgml +++ b/doc/src/sgml/fuzzystrmatch.sgml @@ -1,7 +1,7 @@ - fuzzystrmatch determine string similarities and distance + fuzzystrmatch determine string similarities and distance [trusted] fuzzystrmatch diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index 7d93e49e91..b75c63f348 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -1,7 +1,7 @@ - hstore hstore key/value datatype + hstore hstore key/value datatype [trusted] hstore diff --git a/doc/src/sgml/intagg.sgml b/doc/src/sgml/intagg.sgml index 44a766eb4b..ce7b929a34 100644 --- a/doc/src/sgml/intagg.sgml +++ b/doc/src/sgml/intagg.sgml @@ -1,7 +1,7 @@ - intagg integer aggregator and enumerator + intagg integer aggregator and enumerator [obsolete] intagg diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index c72d49b01d..9194e94c28 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -1,7 +1,7 @@ - intarray manipulate arrays of integers + intarray manipulate arrays of integers [trusted] intarray diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index ea2aabc87d..a609969af9 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -1,7 +1,7 @@ - isn data types for international standard numbers (ISBN, EAN, UPC, etc.) + isn data types for international standard numbers (ISBN, EAN, UPC, etc.) [trusted] isn diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml index 6d9bcebd42..511e576cac 100644 --- a/doc/src/sgml/lo.sgml +++ b/doc/src/sgml/lo.sgml @@ -1,7 +1,7 @@ - lo manage large objects + lo manage large objects [trusted] lo diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index bb66e33944..25d98e3f7d 100644 --- a/doc/src/sgml/ltree.sgml +++
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On 2023-Jan-20, Karl O. Pinc wrote: > On Fri, 20 Jan 2023 12:42:31 +0100 > Alvaro Herrera 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 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 s get a pagebreak", in a way that doesn't affect the other chapters. The 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 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 HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ really, I see PHP as like a strange amalgamation of C, Perl, Shell inflex: you know that "amalgam" means "mixture with mercury", more or less, right? i.e., "deadly poison"
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Fri, 20 Jan 2023 12:42:31 +0100 Alvaro Herrera wrote: > On 2023-Jan-19, Karl O. Pinc wrote: > > > On Thu, 19 Jan 2023 11:03:53 -0600 > > "Karl O. Pinc" 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On 2023-Jan-19, Karl O. Pinc wrote: > On Thu, 19 Jan 2023 11:03:53 -0600 > "Karl O. Pinc" 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 >From 15cf3a5607ec73900c5e3bb343ab687f1e6990c1 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Thu, 19 Jan 2023 13:32:35 +0100 Subject: [PATCH v6 1/3] Describe each contrib module in its SGML section title The original titles only had the module name, which is not very useful when scanning the list. By adding a very brief description to each title, the table of contents becomes friendlier. Author: Karl O. Pinc Reviewed-by: Brar Piening Discussion: https://postgr.es/m/20230102180015.37299...@slate.karlpinc.com --- doc/src/sgml/adminpack.sgml | 2 +- doc/src/sgml/amcheck.sgml | 2 +- doc/src/sgml/auth-delay.sgml | 2 +- doc/src/sgml/auto-explain.sgml| 2 +- doc/src/sgml/basebackup-to-shell.sgml | 2 +- doc/src/sgml/basic-archive.sgml | 2 +- doc/src/sgml/bloom.sgml | 2 +- doc/src/sgml/btree-gin.sgml | 4 +-- doc/src/sgml/btree-gist.sgml | 2 +- doc/src/sgml/citext.sgml | 2 +- doc/src/sgml/contrib-spi.sgml | 2 +- doc/src/sgml/contrib.sgml | 49 +++ doc/src/sgml/cube.sgml| 2 +- doc/src/sgml/dblink.sgml | 2 +- doc/src/sgml/dict-int.sgml| 3 +- doc/src/sgml/dict-xsyn.sgml | 2 +- doc/src/sgml/earthdistance.sgml | 2 +- doc/src/sgml/file-fdw.sgml| 2 +- doc/src/sgml/fuzzystrmatch.sgml | 3 +- doc/src/sgml/hstore.sgml | 2 +- doc/src/sgml/intagg.sgml | 2 +- doc/src/sgml/intarray.sgml| 2 +- doc/src/sgml/isn.sgml | 2 +- doc/src/sgml/lo.sgml | 2 +- doc/src/sgml/ltree.sgml | 2 +- doc/src/sgml/oldsnapshot.sgml | 2 +- doc/src/sgml/pageinspect.sgml | 2 +- doc/src/sgml/passwordcheck.sgml | 2 +- doc/src/sgml/pgbuffercache.sgml | 2 +- doc/src/sgml/pgcrypto.sgml| 2 +- doc/src/sgml/pgfreespacemap.sgml | 2 +- doc/src/sgml/pgprewarm.sgml | 2 +- doc/src/sgml/pgrowlocks.sgml | 2 +- doc/src/sgml/pgstatstatements.sgml| 3 +- doc/src/sgml/pgstattuple.sgml | 2 +- doc/src/sgml/pgsurgery.sgml | 2 +- doc/src/sgml/pgtrgm.sgml | 3 +- doc/src/sgml/pgvisibility.sgml| 2 +- doc/src/sgml/pgwalinspect.sgml| 2 +- doc/src/sgml/postgres-fdw.sgml| 3 +- doc/src/sgml/seg.sgml | 2 +- doc/src/sgml/sepgsql.sgml | 3 +- doc/src/sgml/sslinfo.sgml | 2 +- doc/src/sgml/tablefunc.sgml | 2 +- doc/src/sgml/tcn.sgml | 2 +- doc/src/sgml/test-decoding.sgml | 2 +- doc/src/sgml/tsm-system-rows.sgml | 3 +- doc/src/sgml/tsm-system-time.sgml | 3 +- doc/src/sgml/unaccent.sgml| 2 +- doc/src/sgml/uuid-ossp.sgml | 2 +- doc/src/sgml/xml2.sgml| 2 +- 51 files changed, 86 insertions(+), 73 deletions(-) diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 184e96d7a0..04f3b52379 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -1,7 +1,7 @@ - adminpack + adminpack pgAdmin support toolpack adminpack diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 923cbde9dd..2b9c1a9205 100644 ---
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Thu, 19 Jan 2023 11:03:53 -0600 "Karl O. Pinc" 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Thu, 19 Jan 2023 13:35:17 +0100 Alvaro Herrera 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index c9efe1cccf..f0cda0e32a 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,7 +1,8 @@ - btree_gin GIN B-tree equivalent operator classes [trusted] + btree_gin + GIN B-tree equivalent operator classes [trusted] btree_gin diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 27abdc8c66..8008c84fe4 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -1,8 +1,8 @@ - isn - data types for item numbers (ISBN, EAN, UPC, etc.) [trusted] + isn data types for international standard numbers + (ISBN, EAN, UPC, etc.) [trusted] isn diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 184e96d7a0..04f3b52379 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -1,7 +1,7 @@ - adminpack + adminpack pgAdmin support toolpack adminpack diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 923cbde9dd..4006c75cdf 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -1,7 +1,7 @@ - amcheck + amcheck tools to verify index consistency amcheck diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 40629311b1..0571f2a99d 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -1,7 +1,7 @@ - auth_delay + auth_delay pause on authentication failure auth_delay diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index bb7342b120..0c4656ee30 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -1,7 +1,7 @@ - auto_explain + auto_explain log execution plans of slow queries auto_explain diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml index 491368eb8f..b6a3b39541 100644 --- a/doc/src/sgml/basebackup-to-shell.sgml +++ b/doc/src/sgml/basebackup-to-shell.sgml @@ -1,7 +1,7 @@ - basebackup_to_shell + basebackup_to_shell example "shell" pg_basebackup module basebackup_to_shell diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml index 60f23d2855..b4d43ced20 100644 --- a/doc/src/sgml/basic-archive.sgml +++ b/doc/src/sgml/basic-archive.sgml @@ -1,7 +1,7 @@ - basic_archive + basic_archive an example WAL archive module basic_archive diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index 98d0316175..19f2b172cc 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -1,7 +1,7 @@ - bloom + bloom bloom filter index access method bloom diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 870c25559e..f0cda0e32a 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,14 +1,15 @@ - btree_gin + btree_gin + GIN B-tree equivalent operator classes [trusted] btree_gin - btree_gin provides sample GIN operator classes that + btree_gin provides GIN operator classes that implement B-tree equivalent behavior for the data types int2, int4, int8, float4, float8, timestamp with time zone, diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index 92aa8e277e..c08d1fdfc3 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -1,7 +1,8 @@ - btree_gist + btree_gist + B-tree equivalent GiST index operators [trusted] btree_gist diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml index 3df2825592..710fbdddf2 100644 --- a/doc/src/sgml/citext.sgml +++ b/doc/src/sgml/citext.sgml @@ -1,7 +1,8 @@ - citext + citext + a case-insensitive character string type [trusted] citext diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml index 77328ae6e8..e7cae4e38d 100644 --- a/doc/src/sgml/contrib-spi.sgml +++
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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 HerreraBreisgau, 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/) commit fcdf3ceb0579f4b308b39ee6a957fe47a66bde32 Author: Alvaro Herrera [Álvaro Herrera ] AuthorDate: Thu Jan 19 13:33:12 2023 +0100 CommitDate: Thu Jan 19 13:33:12 2023 +0100 Alvaro review diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index 672ac2ed19..19f2b172cc 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -1,7 +1,7 @@ - bloom bloom filter index access + bloom bloom filter index access method bloom diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 0eaea0dbcd..c9efe1cccf 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,15 +1,14 @@ - btree_gin - sample GIN B-tree equivalent operator classes [trusted] + btree_gin GIN B-tree equivalent operator classes [trusted] btree_gin - btree_gin provides sample GIN operator classes that + btree_gin provides GIN operator classes that implement B-tree equivalent behavior for the data types int2, int4, int8, float4, float8, timestamp with time zone, diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 810ca73f81..8816e06337 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -1,7 +1,7 @@ - Additional Supplied Modules and Extensions + Additional Supplied Extensions and Modules This appendix and the next one contain information on the @@ -55,7 +55,8 @@ - Many components supply new user-defined functions, operators, or types. + Many components supply new user-defined functions, operators, or types, + packaged as extensions. To make use of one of these extensions, after you have installed the code you need to register the new SQL objects in the database system. This is done by executing @@ -66,7 +67,7 @@ CREATE EXTENSION extension_name; - This command registers the new SQL objects in the current database only, + This command only registers the new SQL objects in the current database, so you need to run it in every database in which you want the extension's facilities to be available. Alternatively, run it in database template1 so that the extension will be copied into diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 0568436a26..27abdc8c66 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -2,7 +2,7 @@ isn - data types for various ISN standards (UPC, books, etc.) [trusted] + data types for item numbers (ISBN, EAN, UPC, etc.) [trusted] isn diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml index c51781b0bb..511e576cac 100644 --- a/doc/src/sgml/lo.sgml +++ b/doc/src/sgml/lo.sgml @@ -1,7 +1,7 @@ - lo manage large objects (BLOBs) [trusted] + lo manage large objects [trusted] lo
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Wed, 18 Jan 2023 18:34:47 +0100 Alvaro Herrera wrote: > On 2023-Jan-18, Karl O. Pinc wrote: > > > On Wed, 18 Jan 2023 13:30:45 +0100 > > Alvaro Herrera 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. > > > > > 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Wed, 18 Jan 2023 13:25:57 +0100 Alvaro Herrera 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. > > 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 184e96d7a0..04f3b52379 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -1,7 +1,7 @@ - adminpack + adminpack pgAdmin support toolpack adminpack diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 923cbde9dd..4006c75cdf 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -1,7 +1,7 @@ - amcheck + amcheck tools to verify index consistency amcheck diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 40629311b1..0571f2a99d 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -1,7 +1,7 @@ - auth_delay + auth_delay pause on authentication failure auth_delay diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index bb7342b120..0c4656ee30 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -1,7 +1,7 @@ - auto_explain + auto_explain log execution plans of slow queries auto_explain diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml index 491368eb8f..b6a3b39541 100644 --- a/doc/src/sgml/basebackup-to-shell.sgml +++ b/doc/src/sgml/basebackup-to-shell.sgml @@ -1,7 +1,7 @@ - basebackup_to_shell + basebackup_to_shell example "shell" pg_basebackup module basebackup_to_shell diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml index 60f23d2855..b4d43ced20 100644 --- a/doc/src/sgml/basic-archive.sgml +++ b/doc/src/sgml/basic-archive.sgml @@ -1,7 +1,7 @@ - basic_archive + basic_archive an example WAL archive module basic_archive diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index 98d0316175..672ac2ed19 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -1,7 +1,7 @@ - bloom + bloom bloom filter index access bloom diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 870c25559e..0eaea0dbcd 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -1,7 +1,8 @@ - btree_gin + btree_gin + sample GIN B-tree equivalent operator
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On 2023-Jan-18, Karl O. Pinc wrote: > On Wed, 18 Jan 2023 13:30:45 +0100 > Alvaro Herrera 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. > > > 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)
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Wed, 18 Jan 2023 13:30:45 +0100 Alvaro Herrera 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. > 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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)
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
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
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On Sun, 15 Jan 2023 07:11:30 +0100 Brar Piening 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 Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
On 03.01.2023 at 01:00, Karl O. Pinc wrote: Attached is a patch: contrib_v1.patch It modifies Appendix F, the contrib directory. Review: The patch applies cleanly (1334b79a35 - 2023-01-14 18:05:09 +0900). It adds a brief explanatory part to the headers of all contrib modules which I consider as very useful, especially when looking at the TOC in contrib.html where currently newcomers would need to click through all the links to even get an idea what the various modules do. The explanatory parts added make sense to me, althogh I'm not an expert in all the different contrib modules. Appendix F. now reads as "Additional Supplied Modules and Extensions" instead of "Appendix F. Additional Supplied Modules" which IMHO proprely reflects what it is about. The original title probably comes from the pre-extension-era. There is also some minor rewording of sentences in contrib.sgml that in general looks like an improvment to me. In conclusion I cannot see why this patch should not be applied in it's current form so I deem it ready for commiter. Regards, Brar
