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