Thread: Duplicating website's formatting in local doc builds
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
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
Attachment
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
Attachment
"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
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
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
Attachment
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
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
Attachment
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
Attachment
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
Attachment
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
Attachment
"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
Attachment
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
Attachment
"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
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
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
Attachment
"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
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