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

On Wed, 18 Jan 2023 13:25:57 +0100
Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)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(at)karlpinc(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein