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

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

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

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

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

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

But first, a summary:

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

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

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


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

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

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

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

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

Sorry to run-on.  Thinking out loud.

Regards,

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