Re: Duplicating website's formatting in local doc builds

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