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

From: "Jonathan S. Katz" <[email-masked]>
Date: Wed, 29 Mar 2023 13:17:33 -0400

On 3/23/23 5:45 AM, Alvaro Herrera wrote:
> On 2023-Mar-22, Karl O. Pinc wrote:
> 
>> Hi,
>>
>> I rebuilt the HEAD (master) html with:
>>
>>    make STYLE=website html
>>
>> and what I see locally is still different from
>> what is on postgresql.org.
>>
>> So the build system does indeed seem to be generating
>> "different html" that looks un-good compared to what
>> Alvaro and I are seeing when we build locally.
> 
> Hah, you're right -- the website is missing the closing </p>.  Weird.
> It is definitely possible that the website is using outdated XSLT
> stylesheets.  For example, at the top of the page in my local build I
> see this:
> 
> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>
> 
> whereas the website only says
> 
> <!doctype html>
> <html lang="en">
>   <head>

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

I haven't gone through the the doc loading process in awhile, but what 
happens is that the docs build with the HTML generated (make html) and 
then are processed and "uploaded" to the website through this code[1]. 
It's possible that somewhere in the "HTML tidy" process something may be 
removed.

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?

Jonathan

[1] 
https://git.postgresql.org/gitweb/?p=pgweb.git;a=blob;f=tools/docs/docload.py;hb=HEAD

---

From: "Karl O. Pinc" <[email-masked]>
Date: Wed, 29 Mar 2023 13:23:33 -0500

On Wed, 29 Mar 2023 13:17:33 -0400

> 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 <[email-masked]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein