Horton

Thread

Commits

  1. Recreate website's formatting for "website" doc builds.

  1. Duplicating website's formatting in local doc builds

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-02-11T18:37:13Z

    I'm wondering how to do $SUBJECT.  The fine manual suggests

	make STYLE=website html

but what I'm getting here with that is not a very close approximation
of what I see at postgresql.org.  It's closer than the default,
but it's not the same font, margins, etc.

I also wonder why duplicating the website's style isn't the default.
Doesn't seem like having authors optimize for some other style is
what we really want.

			regards, tom lane

  2. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-11T18:59:10Z

    On 2/11/20 1:37 PM, Tom Lane wrote:
> I'm wondering how to do $SUBJECT.  The fine manual suggests
> 
> 	make STYLE=website html
> 
> but what I'm getting here with that is not a very close approximation
> of what I see at postgresql.org.  It's closer than the default,
> but it's not the same font, margins, etc.
> 
> I also wonder why duplicating the website's style isn't the default.
> Doesn't seem like having authors optimize for some other style is
> what we really want.

It looks like it's pulling from the wrong source[1]. It should be:


https://www.postgresql.org/dyncss/base.css

There are a few more dependencies now as well to get the Bootstrap
structure and the font:

https://www.postgresql.org/media/css/fontawesome.css
https://www.postgresql.org/media/css/bootstrap.min.css

(And one for another font...which I see we should import the dependency on).

This should likely be a small quick change. I was going to try to say
"after the release" comment, but given I'm in both codebases at the
moment, I'll do a quick test and see how it looks.

(FWIW, I test the appearance a bit differently. I actually import built
documentation into my local copy of pgweb and tinker from there, as I'll
have all the dependencies available. That likely is not a viable option
for most people working on the documentation [unless we make it easier
to get pgweb up and running]).

Jonathan

[1]
https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/stylesheet.xsl;hb=HEAD#l26

  3. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-11T19:00:57Z

    On 2/11/20 1:37 PM, Tom Lane wrote:

> I also wonder why duplicating the website's style isn't the default.
> Doesn't seem like having authors optimize for some other style is
> what we really want.

Oh, and specifically for this, my guess is because it requires one to
make a call over a network to load the stylesheet. :)

Jonathan

  4. Re: Duplicating website's formatting in local doc builds

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-02-11T19:32:11Z

    "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 2/11/20 1:37 PM, Tom Lane wrote:
>> I also wonder why duplicating the website's style isn't the default.
>> Doesn't seem like having authors optimize for some other style is
>> what we really want.

> Oh, and specifically for this, my guess is because it requires one to
> make a call over a network to load the stylesheet. :)

Surely we could provide directions about how to store that locally.

			regards, tom lane

  5. Re: Duplicating website's formatting in local doc builds

    Peter Geoghegan <pg@bowt.ie> — 2020-02-11T19:33:25Z

    On Tue, Feb 11, 2020 at 10:37 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I also wonder why duplicating the website's style isn't the default.
> Doesn't seem like having authors optimize for some other style is
> what we really want.

FWIW, I've often wondered about it myself.

-- 
Peter Geoghegan

  6. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-11T19:40:44Z

    On 2/11/20 2:32 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 2/11/20 1:37 PM, Tom Lane wrote:
>>> I also wonder why duplicating the website's style isn't the default.
>>> Doesn't seem like having authors optimize for some other style is
>>> what we really want.
> 
>> Oh, and specifically for this, my guess is because it requires one to
>> make a call over a network to load the stylesheet. :)
> 
> Surely we could provide directions about how to store that locally.

I have a little doubt about that, but per mention in the original email,
it means storing a lot more stylesheets and ones that may change with
more frequency than the project. It may not be too much of an issue, but
I do want to note that. I'm somewhat ambivalent myself, but my
preference is to have the single source of truth.

Anyway, attached is a first attempt at a patch. I tried a few different
variations but in my quick review of it, I could not figure out how to
make a XSLT respect having multiple stylesheets (likely due to my lack
of familiarity with XSLT).

This just swaps out the link. A better approach would be to find a way
to include multiple CSS stylesheets. After searching over a bunch of
different terms, I could not figure out how to get to this result, but
as mentioned, I'm close to clueless on writing XSLT at this point.

Another way we could get to the desired result add something to pgweb
similar to the old "docs.css" that is being referenced that combines the
multiple stylesheets into one. It's a bit of an anti-pattern in modern
web, so I'm not thrilled to go down that route.

Jonathan

  7. Re: Duplicating website's formatting in local doc builds

    Peter Geoghegan <pg@bowt.ie> — 2020-02-11T20:41:34Z

    On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
> Anyway, attached is a first attempt at a patch. I tried a few different
> variations but in my quick review of it, I could not figure out how to
> make a XSLT respect having multiple stylesheets (likely due to my lack
> of familiarity with XSLT).

I tried this patch out. The alignment is a little off, since the docs
don't appear in the website's frame, and lack the website's header. It
would be nice if the same margins appeared to the left and to the
right. But even still, it's a vast improvement.

There are a couple of inconsistencies in the tables and diagrams that
appear on this documentation page (on my local build that uses your
patch):

https://www.postgresql.org/docs/devel/storage-page-layout.html

The tables look different, which isn't too bad. The "Figure 68.1. Page
Layout" diagram is massive, though. IIRC was an issue that had to be
addressed on the website a little after the introduction of images
into the docs. It seems as if my local build of the docs needs that
same fix.

-- 
Peter Geoghegan

  8. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-11T20:49:53Z

    On 2/11/20 3:41 PM, Peter Geoghegan wrote:
> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>> Anyway, attached is a first attempt at a patch. I tried a few different
>> variations but in my quick review of it, I could not figure out how to
>> make a XSLT respect having multiple stylesheets (likely due to my lack
>> of familiarity with XSLT).
> 
> I tried this patch out.

Thanks!

> The alignment is a little off, since the docs
> don't appear in the website's frame, and lack the website's header. It
> would be nice if the same margins appeared to the left and to the
> right. 

Yup, that's a direct result of not having the Bootstrap base.

> But even still, it's a vast improvement.

Cool.

>>
> There are a couple of inconsistencies in the tables and diagrams that
> appear on this documentation page (on my local build that uses your
> patch):
> 
> https://www.postgresql.org/docs/devel/storage-page-layout.html
> 
> The tables look different, which isn't too bad. The "Figure 68.1. Page
> Layout" diagram is massive, though. IIRC was an issue that had to be
> addressed on the website a little after the introduction of images
> into the docs. It seems as if my local build of the docs needs that
> same fix.

Ditto on missing the Bootstrap base. The tables rely directly on that
base for the style an formatting. For the images, the CSS classes are:

"figure col-xl-8 col-lg-10 col-md-12"

"figure" is one of our custom defined classes, but the rest are
Bootstrap and are designed to size to the particular browser window
resolution.

(For the history of the figure sizing, it was two fixes:

1. One with the SVG generation to allow for it to scale (the "S" in SVG
:) and then
2. Applying the CSS classes shown above.


Without the CSS classes, the image will scale without limit)

Jonathan

  9. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-12T03:56:27Z

    On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>> variations but in my quick review of it, I could not figure out how to
>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>> of familiarity with XSLT).
>>
>> I tried this patch out.
> 
> Thanks!
> 
>> The alignment is a little off, since the docs
>> don't appear in the website's frame, and lack the website's header. It
>> would be nice if the same margins appeared to the left and to the
>> right. 
> 
> Yup, that's a direct result of not having the Bootstrap base.
> 
>> But even still, it's a vast improvement.
> 
> Cool.

I played around with this for a bit longer, became a bit more familiar
with DocBook[1] (and a lot of other pages, but this one seemed
relevant), and here is what I came up with:

As I mentioned, the way pgweb works is that it wraps a root element (the
<div id="docContent">...</div>) around the imported HTMl from the
generation, which allows it to apply the various website styles. This is
important, because it allows us to apply some general style rules, but
namespace them specifically to the documentation. Hold this thought for
a moment.

When calling "make STYLE=website html", this turns on a flag that embeds
the URL to the old "docs.css" content that we generated. I did an
experiment where I overloaded the "dynamic CSS generator" we have in our
code to include the bootstrap.css files (as well as some others) in
addition to our new base CSS. This demonstrated a marked improvement in
the output from the above command, but it was still not perfect: the CSS
rules still expect there to be the #docContent namespace.

I thought this would be a good area to explore to see if I could get the
#docContent ID wrapped around the content body. As I was writing this
note (where actually I was about to throw in the towel), on a hunch I
improved my Googling and found a solution (attached).

This works with pgweb as pgweb extracts the content from the <body> tag
that is generated by "make html" so this is unaffected.

For this solution to fully work, I also need to make a patch to pgweb. I
have it 80% done, where the final 20% is getting rid of some annoying
errors of files it is looking for (the Bootstrap minification expects a
CSS map file. I believe I can silence that).

It's not perfect: we don't have a full container around the generated
documentation so you can't see it exactly in terms of how it's render on
the website, but it's way closer to the look and feel. I might be able
to add a few more attributes to make it look closer to the website in
that regard, though after there is consensus that this approach is ok.

That said, I think this is a happy compromise that allows said mode to
appear mostly like what you would find on the website.

Thanks,

Jonathan

[1] http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html

  10. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-12T13:15:08Z

    On 2/11/20 10:56 PM, Jonathan S. Katz wrote:
> On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
>> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>>> variations but in my quick review of it, I could not figure out how to
>>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>>> of familiarity with XSLT).
>>>
>>> I tried this patch out.
>>
>> Thanks!
>>
>>> The alignment is a little off, since the docs
>>> don't appear in the website's frame, and lack the website's header. It
>>> would be nice if the same margins appeared to the left and to the
>>> right. 
>>
>> Yup, that's a direct result of not having the Bootstrap base.
>>
>>> But even still, it's a vast improvement.
>>
>> Cool.
> 
> I played around with this for a bit longer, became a bit more familiar
> with DocBook[1] (and a lot of other pages, but this one seemed
> relevant), and here is what I came up with:
> 
> As I mentioned, the way pgweb works is that it wraps a root element (the
> <div id="docContent">...</div>) around the imported HTMl from the
> generation, which allows it to apply the various website styles. This is
> important, because it allows us to apply some general style rules, but
> namespace them specifically to the documentation. Hold this thought for
> a moment.
> 
> When calling "make STYLE=website html", this turns on a flag that embeds
> the URL to the old "docs.css" content that we generated. I did an
> experiment where I overloaded the "dynamic CSS generator" we have in our
> code to include the bootstrap.css files (as well as some others) in
> addition to our new base CSS. This demonstrated a marked improvement in
> the output from the above command, but it was still not perfect: the CSS
> rules still expect there to be the #docContent namespace.
> 
> I thought this would be a good area to explore to see if I could get the
> #docContent ID wrapped around the content body. As I was writing this
> note (where actually I was about to throw in the towel), on a hunch I
> improved my Googling and found a solution (attached).
> 
> This works with pgweb as pgweb extracts the content from the <body> tag
> that is generated by "make html" so this is unaffected.
> 
> For this solution to fully work, I also need to make a patch to pgweb. I
> have it 80% done, where the final 20% is getting rid of some annoying
> errors of files it is looking for (the Bootstrap minification expects a
> CSS map file. I believe I can silence that).
> 
> It's not perfect: we don't have a full container around the generated
> documentation so you can't see it exactly in terms of how it's render on
> the website, but it's way closer to the look and feel. I might be able
> to add a few more attributes to make it look closer to the website in
> that regard, though after there is consensus that this approach is ok.
> 
> That said, I think this is a happy compromise that allows said mode to
> appear mostly like what you would find on the website.

Realizing this might be a bit wonky to test, I made the necessary
changes to pgweb and pushed those, so the results of the patch now look
like what I was seeing. If you were previously testing it, rebuild the
docs with STYLE=website and it should now look better.

Thanks,

Jonathan

  11. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-14T22:43:57Z

    On 2/12/20 8:15 AM, Jonathan S. Katz wrote:
> On 2/11/20 10:56 PM, Jonathan S. Katz wrote:
>> On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
>>> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>>>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>>>> variations but in my quick review of it, I could not figure out how to
>>>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>>>> of familiarity with XSLT).
>>>>
>>>> I tried this patch out.
>>>
>>> Thanks!
>>>
>>>> The alignment is a little off, since the docs
>>>> don't appear in the website's frame, and lack the website's header. It
>>>> would be nice if the same margins appeared to the left and to the
>>>> right. 
>>>
>>> Yup, that's a direct result of not having the Bootstrap base.
>>>
>>>> But even still, it's a vast improvement.
>>>
>>> Cool.
>>
> Realizing this might be a bit wonky to test, I made the necessary
> changes to pgweb and pushed those, so the results of the patch now look
> like what I was seeing. If you were previously testing it, rebuild the
> docs with STYLE=website and it should now look better.

Alright, so after some offline image sharing and a bit more
experimenting, I will skip ahead and present v4 of this patch, which,
believe it or not, makes the documentation page. Notable changes since
v2 include:

- Margins!
- The webfont we use (Open Sans) properly loads

The original approach was to leverage just a single CSS file that was
bundled up by our "dynamic CSS" loader in pgweb. As CSS is "cascading",
we need to include the dependencies (e.g. Bootstrap) prior to loading
our own styles.

To load the webfont, the "main.css" file uses a CSS "@import"
instruction, which has a limitation that it can only be used as the top
of the file. As main.css is not the first file in the "docs.csS"
sandwich, it does not load.

Buried in some version of the DocBook[1] documentation were in
instructions on how to load in multiple stylesheets via

	<xsl:param name="html.stylesheet">

which I followed in our XSLT, which lead to that portion of the diff.

The margins, which is likely the most exciting piece of all this, weree
relatively trivial once I realized how we could override at least one of
the CSS classes.

Not included is one of Tom's original questions, which is should we just
make using the website styles the default? As it stands, this would
require network connectivity to preview the look for a page. If we want
to ensure consistent views across the board, then I would say we import
the stylesheets, knowing that "main.css" is volatile.

Otherwise, for the immediate issue of "make STYLE=website html" being
inaccurate with the current state of the doc pages, I submit this patch
for consideration.

Thanks,

Jonathan

[1]
http://docbook.sourceforge.net/release/xsl/current/doc/html/html.stylesheet.html

  12. Re: Duplicating website's formatting in local doc builds

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-02-14T23:06:18Z

    "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> To load the webfont, the "main.css" file uses a CSS "@import"
> instruction, which has a limitation that it can only be used as the top
> of the file. As main.css is not the first file in the "docs.csS"
> sandwich, it does not load.
> Buried in some version of the DocBook[1] documentation were in
> instructions on how to load in multiple stylesheets via
> 	<xsl:param name="html.stylesheet">
> which I followed in our XSLT, which lead to that portion of the diff.

It looks to me like the main text font now matches, but the font used for
<literal> text doesn't quite -- see the attached, and note for example the
capital T's in CREATE TYPE.  (Local build with this patch on the left,
website on the right.)  Still, it's enormously closer than before.

> Not included is one of Tom's original questions, which is should we just
> make using the website styles the default? As it stands, this would
> require network connectivity to preview the look for a page. If we want
> to ensure consistent views across the board, then I would say we import
> the stylesheets, knowing that "main.css" is volatile.

The point about network access seems to me to be sufficient reason not
to make it the default.  I'd actually say that we ought to annotate
section J.3.1 to point out that "make STYLE=website" will result in
that.  However, I'm not quite clear on whether that means external
access during viewing, or during build, or both?  The note should say.

			regards, tom lane

  13. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-15T01:21:23Z

    On 2/14/20 6:06 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> To load the webfont, the "main.css" file uses a CSS "@import"
>> instruction, which has a limitation that it can only be used as the top
>> of the file. As main.css is not the first file in the "docs.csS"
>> sandwich, it does not load.
>> Buried in some version of the DocBook[1] documentation were in
>> instructions on how to load in multiple stylesheets via
>> 	<xsl:param name="html.stylesheet">
>> which I followed in our XSLT, which lead to that portion of the diff.
> 
> It looks to me like the main text font now matches, but the font used for
> <literal> text doesn't quite -- see the attached, and note for example the
> capital T's in CREATE TYPE.  (Local build with this patch on the left,
> website on the right.)  Still, it's enormously closer than before.

Hmm, I'm not getting that. They're both identical for me, at least in
Chrome...

...but I hopped over into Safari, and I saw a difference between the
local file in Chrome, and what .org looks like in Safari.

I dove into this a bit. For this view, we are just using the default
"monospace" font that is referenced by a particular browser. It seems
like there was a change in Safari 12 where you can no longer override
the default monospace font. It appears to be using "SF Mono."

In Chrome, it appears that it is using Courier.

A potential solution is that we drop the use of "monospace" in relying
on the OS default and just pick a font. I would say that this is outside
the scope of the patch that's being proposed, but certainly something to
look into on the pgweb side given we're creating an inconsistent
cross-browser experience.

> 
>> Not included is one of Tom's original questions, which is should we just
>> make using the website styles the default? As it stands, this would
>> require network connectivity to preview the look for a page. If we want
>> to ensure consistent views across the board, then I would say we import
>> the stylesheets, knowing that "main.css" is volatile.
> 
> The point about network access seems to me to be sufficient reason not
> to make it the default.  I'd actually say that we ought to annotate
> section J.3.1 to point out that "make STYLE=website" will result in
> that.  However, I'm not quite clear on whether that means external
> access during viewing, or during build, or both?  The note should say.

It would only be during viewing -- the build just puts the URL into the
HTML file.

But don't take my word for it, please see the attached patch ;)

Jonathan

  14. Re: Duplicating website's formatting in local doc builds

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-02-15T01:51:39Z

    "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> A potential solution is that we drop the use of "monospace" in relying
> on the OS default and just pick a font. I would say that this is outside
> the scope of the patch that's being proposed, but certainly something to
> look into on the pgweb side given we're creating an inconsistent
> cross-browser experience.

Agreed, not in-scope for this patch.

>> The point about network access seems to me to be sufficient reason not
>> to make it the default.  I'd actually say that we ought to annotate
>> section J.3.1 to point out that "make STYLE=website" will result in
>> that.  However, I'm not quite clear on whether that means external
>> access during viewing, or during build, or both?  The note should say.

> It would only be during viewing -- the build just puts the URL into the
> HTML file.

OK.

> But don't take my word for it, please see the attached patch ;)

Hm, I wouldn't go into that much detail; it'd likely soon be out of
date anyway.  I had in mind something more like "If the STYLE=website
option is used, the generated HTML files will include references to
stylesheets hosted at www.postgresql.org, so that viewing them will
require network access."

			regards, tom lane

  15. Re: Duplicating website's formatting in local doc builds

    Peter Geoghegan <pg@bowt.ie> — 2020-02-15T01:56:10Z

    On Fri, Feb 14, 2020 at 5:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Hm, I wouldn't go into that much detail; it'd likely soon be out of
> date anyway.  I had in mind something more like "If the STYLE=website
> option is used, the generated HTML files will include references to
> stylesheets hosted at www.postgresql.org, so that viewing them will
> require network access."

But everything else looks good, right?

I would like to commit this patch shortly.

-- 
Peter Geoghegan

  16. Re: Duplicating website's formatting in local doc builds

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-02-15T02:01:44Z

    On 2/14/20 8:56 PM, Peter Geoghegan wrote:
> On Fri, Feb 14, 2020 at 5:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Hm, I wouldn't go into that much detail; it'd likely soon be out of
>> date anyway.  I had in mind something more like "If the STYLE=website
>> option is used, the generated HTML files will include references to
>> stylesheets hosted at www.postgresql.org, so that viewing them will
>> require network access."
> 
> But everything else looks good, right?
> 
> I would like to commit this patch shortly.

Language updates attached...mostly kept Tom's suggestions.

Thanks,

Jonathan

  17. Re: Duplicating website's formatting in local doc builds

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-02-15T02:09:34Z

    "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 2/14/20 8:56 PM, Peter Geoghegan wrote:
>> But everything else looks good, right?
>> I would like to commit this patch shortly.

> Language updates attached...mostly kept Tom's suggestions.

Typo (optoin), otherwise LGTM.

			regards, tom lane

  18. Re: Duplicating website's formatting in local doc builds

    Peter Geoghegan <pg@bowt.ie> — 2020-02-15T02:39:34Z

    On Fri, Feb 14, 2020 at 6:09 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Language updates attached...mostly kept Tom's suggestions.
>
> Typo (optoin), otherwise LGTM.

Great. Pushed with that tweak.

-- 
Peter Geoghegan