From: Jonathan S. Katz <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Peter Geoghegan <pg@bowt.ie>
Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: Duplicating website's formatting in local doc builds
Date: Fri, 14 Feb 2020 20:21:23 -0500
Message-ID: <8d663c68-3df0-bf3f-8c2e-e6897a55394a@postgresql.org> (raw)
In-Reply-To: <11007.1581721578@sss.pgh.pa.us>
References: <1375.1581446233@sss.pgh.pa.us>
<d381c45a-880f-7b0d-773d-be117685a6ad@postgresql.org>
<3873.1581449531@sss.pgh.pa.us>
<4b44c4ec-a678-6586-fbb0-efc3299af203@postgresql.org>
<CAH2-Wzka_NfJGfL9UvQ1Jau1gqerat2zR9O0iAm3DgQEAYebJQ@mail.gmail.com>
<dc3089b0-9c40-fc3b-bce1-7fcc16891dd1@postgresql.org>
<86f03290-e60c-855e-786a-d1b75c254811@postgresql.org>
<716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org>
<bd7e5ec0-caa4-56d0-562e-21880e205e02@postgresql.org>
<11007.1581721578@sss.pgh.pa.us>
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
Attachments:website-formatted-docs-v5.patch (text/plain, 3.0K) downloaddiff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgmlindex c99198f5e5..17f2bf42ac 100644--- a/doc/src/sgml/docguide.sgml+++ b/doc/src/sgml/docguide.sgml@@ -276,6 +276,43 @@ checking for fop... fop
<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
</screen>
</para>
++ <para>+ Viewing the documentation built using the <ulink+ url="https://www.postgresql.org/docs/current/">postgresql.org</ulink>+ stylesheet requires Internet connectivity, as the HTML pages contain+ references to remotely hosted stylesheets, including:+ <itemizedlist>+ <listitem>+ <para>+ <ulink url="https://www.postgresql.org/media/css/fontawesome.css">+ https://www.postgresql.org/media/css/fontawesome.css+ </ulink>+ </para>+ </listitem>+ <listitem>+ <para>+ <ulink url="https://www.postgresql.org/media/css/bootstrap.min.css">+ https://www.postgresql.org/media/css/bootstrap.min.css+ </ulink>+ </para>+ </listitem>+ <listitem>+ <para>+ <ulink url="https://www.postgresql.org/media/css/main.css">+ https://www.postgresql.org/media/css/main.css+ </ulink>+ </para>+ </listitem>+ <listitem>+ <para>+ <ulink url="https://www.postgresql.org/media/css/normalize.css">+ https://www.postgresql.org/media/css/normalize.css+ </ulink>+ </para>+ </listitem>+ </itemizedlist>+ </para>
</sect2>
<sect2>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xslindex 9edce52a10..d9961089c6 100644--- a/doc/src/sgml/stylesheet-html-common.xsl+++ b/doc/src/sgml/stylesheet-html-common.xsl@@ -18,6 +18,14 @@
<xsl:param name="link.mailto.url">pgsql-docs@lists.postgresql.org</xsl:param>
<xsl:param name="toc.max.depth">2</xsl:param>
+<!--+ The below allows the stylesheets provided by the website to be applied fully+ to the generated HTML.+ -->+<xsl:template name="body.attributes">+ <xsl:attribute name="id">docContent</xsl:attribute>+ <xsl:attribute name="class">container-fluid col-10</xsl:attribute>+</xsl:template>
<!-- Change display of some elements -->
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xslindex 4ff6e8ed24..bc5a904e0b 100644--- a/doc/src/sgml/stylesheet.xsl+++ b/doc/src/sgml/stylesheet.xsl@@ -23,11 +23,15 @@
<xsl:param name="html.stylesheet">
<xsl:choose>
<xsl:when test="$website.stylesheet = 0">stylesheet.css</xsl:when>
- <xsl:otherwise>https://www.postgresql.org/media/css/docs.css</xsl:otherwise>+ <xsl:otherwise>+ https://www.postgresql.org/media/css/fontawesome.css+ https://www.postgresql.org/media/css/bootstrap.min.css+ https://www.postgresql.org/media/css/main.css+ https://www.postgresql.org/media/css/normalize.css+ </xsl:otherwise>
</xsl:choose>
</xsl:param>
-
<!-- strip directory name from image filerefs -->
<xsl:template match="imagedata/@fileref">
<xsl:value-of select="substring-after(., '/')"/>
signature.asc (application/pgp-signature, 832B) download
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: jkatz@postgresql.org, tgl@sss.pgh.pa.us, pg@bowt.ie, pgsql-docs@lists.postgresql.org
Subject: Re: Duplicating website's formatting in local doc builds
In-Reply-To: <8d663c68-3df0-bf3f-8c2e-e6897a55394a@postgresql.org>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox