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

Hello pgsql-web,

We're looking to improve the contrib docs with a list of trusted
extensions.  In order for that look more presentable, Karl has come up
with the idea of using a <simplelist> table with multiple columns.  That
would normally look quite terrible because the cell contents are too
close to one another, so he came up with the idea of increasing the
padding, as shown in this patch.

I think this is good thing, as it can help us use tabular <simplelist>
in other places too.

This change requires to change main Postgres doc/src/sgml/stylesheet.css 
as Karl suggested here:

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 */
> 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.

... but in addition it needs the pgweb CSS to be updated to match, as in
the attached patch.

What do you think?

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"The eagle never lost so much time, as
when he submitted to learn of the crow." (William Blake)

> On 9 Mar 2023, at 10:27, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> ... but in addition it needs the pgweb CSS to be updated to match, as in
> the attached patch.
> 
> What do you think?

LGTM.

--
Daniel Gustafsson

On 3/9/23 4:35 AM, Daniel Gustafsson wrote:
>> On 9 Mar 2023, at 10:27, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
> 
>> ... but in addition it needs the pgweb CSS to be updated to match, as in
>> the attached patch.
>>
>> What do you think?
> 
> LGTM.

I'm OK with the change, I'm not OK with the comment around it because 
"Simplelist" doesn't really give meaning to it AFAICT. Maybe:

/** Additional formatting for "simplelist" structures */
#docContent table.simplelist td {
    padding-left: 2em;
    padding-right: 2em;
}

Jonathan

On 2023-Mar-09, Jonathan S. Katz wrote:

> I'm OK with the change, I'm not OK with the comment around it because
> "Simplelist" doesn't really give meaning to it AFAICT. Maybe:
> 
> /** Additional formatting for "simplelist" structures */
> #docContent table.simplelist td {
>     padding-left: 2em;
>     padding-right: 2em;
> }

Uh, absolutely.  Here's a complete patch (in case you wanted that),
thanks.

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"Las cosas son buenas o malas segun las hace nuestra opinión" (Lisias)

On 3/9/23 1:36 PM, Alvaro Herrera wrote:
> On 2023-Mar-09, Jonathan S. Katz wrote:
> 
>> I'm OK with the change, I'm not OK with the comment around it because
>> "Simplelist" doesn't really give meaning to it AFAICT. Maybe:
>>
>> /** Additional formatting for "simplelist" structures */
>> #docContent table.simplelist td {
>>     padding-left: 2em;
>>     padding-right: 2em;
>> }
> 
> Uh, absolutely.  Here's a complete patch (in case you wanted that),
> thanks.

LGTM -- pushed. If it's not reflected within a few hours please let me 
know and I'll force clear the caches.

Thanks,

Jonathan

On Mon, 13 Mar 2023 at 09:28, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> > Uh, absolutely.  Here's a complete patch (in case you wanted that),
> > thanks.
>
> LGTM -- pushed. If it's not reflected within a few hours please let me
> know and I'll force clear the caches.

I think this means the patch is committed? I'll update the commitfest
entry as committed but if there's more to be done feel free to fix.

-- 
Gregory Stark
As Commitfest Manager

On Tue, 14 Mar 2023 at 13:49, Gregory Stark (as CFM)
<stark.cfm@gmail.com> wrote:
>
> On Mon, 13 Mar 2023 at 09:28, Jonathan S. Katz <jkatz@postgresql.org> wrote:
> >
> > > Uh, absolutely.  Here's a complete patch (in case you wanted that),
> > > thanks.
> >
> > LGTM -- pushed. If it's not reflected within a few hours please let me
> > know and I'll force clear the caches.
>
> I think this means the patch is committed? I'll update the commitfest
> entry as committed but if there's more to be done feel free to fix.

Hum. Jonathon Katz isn't listed as a committer -- is this a web site
change or something else? Or do we need to add Jonathon?

-- 
greg

Sorry, having read the whole thread I think it's clear. The source
tree patch was committed by Alvaro H in
a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
pgweb change. So I gather this is resolved now and I've marked it
committed by Alvaro.

On Tue, 14 Mar 2023 13:57:57 -0400
Greg Stark <stark@mit.edu> wrote:

> Sorry, having read the whole thread I think it's clear. The source
> tree patch was committed by Alvaro H in
> a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
> pgweb change. So I gather this is resolved now and I've marked it
> committed by Alvaro.

There remains an un-committed patch from this thread/commitfest
entry:
v10-0002-Page-break-before-sect1-in-contrib-appendix-when-pdf.patch

When generating the PDF docs it starts each contrib entry on
a separate page.

From:
https://www.postgresql.org/message-id/20230122144246.0ff87372%40slate.karlpinc.com

I've re-attached the patch.  Nobody has commented directly
on this particular patch, although there was a "looks ok" reply 
to the email.

I don't know what the policy is now that the commitfest entry
is closed.  Perhaps Alvaro was planning on committing it?

Please let me know if I should open up a new
commitfest entry or if there is something else I need to do.

Thanks for the help.

Regards,

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

On 2023-Mar-14, Karl O. Pinc wrote:

> On Tue, 14 Mar 2023 13:57:57 -0400
> Greg Stark <stark@mit.edu> wrote:
> 
> > Sorry, having read the whole thread I think it's clear. The source
> > tree patch was committed by Alvaro H in
> > a7e584a7d68a9a2bcc7efaf442262771f9044248 and then Katz pushed the
> > pgweb change. So I gather this is resolved now and I've marked it
> > committed by Alvaro.

Actually, the 0001 patch hadn't been fully committed yet ... I had only
added the CSS tweaks.  I have now pushed the addition of the tables to
the SGML sources, with minor tag changes: I found that with the
<simplelist> outside of any <para>, the list was too close to the next
paragraph, which looked a bit ugly.  I put the list inside the <para>
that explains what the list is.  It looks good with PDF, website-HTML
and plain-HTML rendering now; didn't look at other output formats.
So, the CF entry being marked committed is now correct as far as I'm
concerned.

> There remains an un-committed patch from this thread/commitfest
> entry:

> 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

> +<!-- Every sect1 in the contrib appendix gets a page break -->
> +<xsl:template match="id('contrib')/sect1">
> +  <fo:block break-after='page'/>
> +  <xsl:apply-imports/>
> +</xsl:template>

Yeah, I think this one achieves what I wanted and isn't a maintenance
burden, but I would like to hear from other CSS people.  I guess I could
just commit it and see what complaints I get (probably none).

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
“Cuando no hay humildad las personas se degradan” (A. Christie)

On Wed, 15 Mar 2023 09:41:27 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> Actually, the 0001 patch hadn't been fully committed yet ... I had
> only added the CSS tweaks.  I have now pushed the addition of the
> tables to the SGML sources, with minor tag changes: I found that with
> the <simplelist> outside of any <para>, the list was too close to the
> next paragraph, which looked a bit ugly.  I put the list inside the
> <para> that explains what the list is.  It looks good with PDF,
> website-HTML and plain-HTML rendering now; didn't look at other
> output formats. So, the CF entry being marked committed is now
> correct as far as I'm concerned.

Thanks for noticing that.  (I'd always vaguely wondered about
lists being inside v.s. outside of paragraphs.  There must be other
places in the docs where this matters.  ?)

> > There remains an un-committed patch from this thread/commitfest
> > entry:  
> 
> > 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  
> 
> > +<!-- Every sect1 in the contrib appendix gets a page break -->
> > +<xsl:template match="id('contrib')/sect1">
> > +  <fo:block break-after='page'/>
> > +  <xsl:apply-imports/>
> > +</xsl:template>  
> 
> Yeah, I think this one achieves what I wanted and isn't a maintenance
> burden, but I would like to hear from other CSS people.  I guess I
> could just commit it and see what complaints I get (probably none).

FWIW, this patch is not to CSS.  It's XSLT and affects only the PDF
generation.

(The patch is a response to your "aside" and remarks regarding a
separate thread, here:
https://www.postgresql.org/message-id/20230118173447.aegjdk3girgkqu2g%40alvherre.pgsql
)

Regards,

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

On 2023-Mar-15, Karl O. Pinc wrote:

> On Wed, 15 Mar 2023 09:41:27 +0100
> Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> > Yeah, I think this one achieves what I wanted and isn't a maintenance
> > burden, but I would like to hear from other CSS people.  I guess I
> > could just commit it and see what complaints I get (probably none).
> 
> FWIW, this patch is not to CSS.  It's XSLT and affects only the PDF
> generation.

Yeah, I misspoke.  I was aware it's XSLT, a territory I'm wholly
unfamiliar with.  I have pushed it now nonetheless.  Thank you!

> (The patch is a response to your "aside" and remarks regarding a
> separate thread, here:
> https://www.postgresql.org/message-id/20230118173447.aegjdk3girgkqu2g%40alvherre.pgsql
> )

Right :-)

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
"El destino baraja y nosotros jugamos" (A. Schopenhauer)

On Mon, 20 Mar 2023 14:16:45 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Mar-15, Karl O. Pinc wrote:

> Yeah, I misspoke.  I was aware it's XSLT, a territory I'm wholly
> unfamiliar with.  I have pushed it now nonetheless.  Thank you!

Thank you for all your help with this.

Regards,

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

Hi,

There seems to be a problem with the html generated
for the public-facing Postgresql docs.

I'm looking at the contrib page in the devel docs,
on the pg website:

https://www.postgresql.org/docs/devel/contrib.html

The simplelist holding the list of trusted extensions,
in doc/src/sgml/contrib.sgml, is inside the paragraph.

But when I look at the delivered html, I see the table
outside of the paragraph.  And the vertical spacing
looks poor as a result.

Alvaro moved the simplelist into the paragraph to
fix just this problem.

Building HEAD (of master) on my computer (Debian 11.6)
what I see is the generation of two paragraphs,
one with the leading text and a second that contains
the simplelist table.  (Er, why 2 paragraphs instead
of just one paragraph with both text and table in
it I can't say.)

The html built on my computer has vertical spacing
that looks good.

Could it be that the build system has out-of-date
docbook xslt?  In any case, it looks like what's
produced for the world to see is different from what
Alvaro and I are seeing.

Regards,

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

P.S.  I don't know what html Alvero is generating,
but his looks good and what's on postgresql.org does
not look good.  So I assume that he's getting something
different from what the public sees now.

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.


On Mon, 20 Mar 2023 15:20:38 -0500
"Karl O. Pinc" <kop@karlpinc.com> wrote:

> There seems to be a problem with the html generated
> for the public-facing Postgresql docs.
> 
> I'm looking at the contrib page in the devel docs,
> on the pg website:
> 
> https://www.postgresql.org/docs/devel/contrib.html
> 
> The simplelist holding the list of trusted extensions,
> in doc/src/sgml/contrib.sgml, is inside the paragraph.
> 
> But when I look at the delivered html, I see the table
> outside of the paragraph.  And the vertical spacing
> looks poor as a result.
> 
> Alvaro moved the simplelist into the paragraph to
> fix just this problem.
> 
> Building HEAD (of master) on my computer (Debian 11.6)
> what I see is the generation of two paragraphs,
> one with the leading text and a second that contains
> the simplelist table.  (Er, why 2 paragraphs instead
> of just one paragraph with both text and table in
> it I can't say.)
> 
> The html built on my computer has vertical spacing
> that looks good.
> 
> Could it be that the build system has out-of-date
> docbook xslt?  In any case, it looks like what's
> produced for the world to see is different from what
> Alvaro and I are seeing.
> 
> Regards,
> 
> Karl <kop@karlpinc.com>
> Free Software:  "You don't pay back, you pay forward."
>                  -- Robert A. Heinlein
> 
> P.S.  I don't know what html Alvero is generating,
> but his looks good and what's on postgresql.org does
> not look good.  So I assume that he's getting something
> different from what the public sees now.


Regards,

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

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"><htmlxmlns="http://www.w3.org/1999/xhtml"><head>
 

whereas the website only says

<!doctype html>
<html lang="en">
 <head>

I don't to waste time investigating that, though.  

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/

Is this the pgsql-www list the right place to report
this so it does not get forgotten?  (If so, no need to reply.)

On Thu, 23 Mar 2023 10:45:51 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Mar-22, Karl O. Pinc wrote:

> > 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.
<snip>

Regards,

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

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"><htmlxmlns="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

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