Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1j2jh4-0006zz-LV for pgsql-docs@arkaria.postgresql.org; Fri, 14 Feb 2020 22:44:19 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1j2jh1-0002ee-86 for pgsql-docs@arkaria.postgresql.org; Fri, 14 Feb 2020 22:44:15 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1j2jh0-0002eX-Jp for pgsql-docs@lists.postgresql.org; Fri, 14 Feb 2020 22:44:15 +0000 Received: from meldrar.postgresql.org ([2a02:c0:301:0:ffff::31]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.92) (envelope-from ) id 1j2jgs-0001v4-Ad for pgsql-docs@lists.postgresql.org; Fri, 14 Feb 2020 22:44:12 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=postgresql.org; s=20171124; h=Content-Type:In-Reply-To:MIME-Version:Date: Message-ID:References:Cc:To:From:Subject:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=u8+1snZ11rfmWY89GCqAkLYf0aNFCIODYNLqPZ+DDRg=; b=3qmrMx6d6aFkrVAz5UcULnmYig QSV80+uZNastaceuBhx5SUviDg+VlCotF5rXZdtOqF5oUkPWfFDG6heJLnF6vjiEtK49+o1IWLg7t mzv7kwFkZq9dXoLHbhArtRwiXg492iT/m1tiDC7ny3xpVRbYuT0l+TD0CbBIFwQPiyMkoJPb1S1lM X2OmBSY+hpzWCzbHt5dgliH6HZ3XFkhKN6O/D30B4dKHw49SEoHsh7rWA7vhR0D7dDZPpEO4gfwQt qGZMkZu9Eyy74VZYr9wXmYk1O7BTZgErvNDOkqvHjaVrJlAdfZp0fLqQn0WsFkgL8Ijoh0N1EBjfV 6Rj+WLsw==; Received: from pool-173-56-10-231.nycmny.fios.verizon.net ([173.56.10.231] helo=Ph33rHippo.home) by meldrar.postgresql.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1j2jgm-0004Rg-Ay; Fri, 14 Feb 2020 22:44:03 +0000 Subject: Re: Duplicating website's formatting in local doc builds From: "Jonathan S. Katz" To: Peter Geoghegan Cc: Tom Lane , Pg Docs References: <1375.1581446233@sss.pgh.pa.us> <3873.1581449531@sss.pgh.pa.us> <4b44c4ec-a678-6586-fbb0-efc3299af203@postgresql.org> <86f03290-e60c-855e-786a-d1b75c254811@postgresql.org> <716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org> Autocrypt: addr=jkatz@postgresql.org; keydata= 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 FmEC Message-ID: Date: Fri, 14 Feb 2020 17:43:57 -0500 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:68.0) Gecko/20100101 Thunderbird/68.4.2 MIME-Version: 1.0 In-Reply-To: <716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="RFhRElG9qZCLUkkLm4WLTQu7aEqcR40sD" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --RFhRElG9qZCLUkkLm4WLTQu7aEqcR40sD Content-Type: multipart/mixed; boundary="1HZsa0ZvQF1mRgpl69naZdXoGVN2A8dwz" --1HZsa0ZvQF1mRgpl69naZdXoGVN2A8dwz Content-Type: multipart/mixed; boundary="------------F5B811F65618A6991F78566B" Content-Language: en-US This is a multi-part message in MIME format. --------------F5B811F65618A6991F78566B Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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 wrote: >>>>> Anyway, attached is a first attempt at a patch. I tried a few diffe= rent >>>>> 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 l= ack >>>>> 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.=20 >>> >>> 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=3Dwebsite 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 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=3Dwebsite 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.styleshe= et.html --------------F5B811F65618A6991F78566B Content-Type: text/plain; charset=UTF-8; x-mac-type="0"; x-mac-creator="0"; name="website-formatted-docs-v4.patch" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="website-formatted-docs-v4.patch" ZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9zdHlsZXNoZWV0LWh0bWwtY29tbW9uLnhzbCBi L2RvYy9zcmMvc2dtbC9zdHlsZXNoZWV0LWh0bWwtY29tbW9uLnhzbAppbmRleCA5ZWRjZTUy YTEwLi5kOTk2MTA4OWM2IDEwMDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvc3R5bGVzaGVldC1o dG1sLWNvbW1vbi54c2wKKysrIGIvZG9jL3NyYy9zZ21sL3N0eWxlc2hlZXQtaHRtbC1jb21t b24ueHNsCkBAIC0xOCw2ICsxOCwxNCBAQAogPHhzbDpwYXJhbSBuYW1lPSJsaW5rLm1haWx0 by51cmwiPnBnc3FsLWRvY3NAbGlzdHMucG9zdGdyZXNxbC5vcmc8L3hzbDpwYXJhbT4KIDx4 c2w6cGFyYW0gbmFtZT0idG9jLm1heC5kZXB0aCI+MjwveHNsOnBhcmFtPgogCis8IS0tCisg IFRoZSBiZWxvdyBhbGxvd3MgdGhlIHN0eWxlc2hlZXRzIHByb3ZpZGVkIGJ5IHRoZSB3ZWJz aXRlIHRvIGJlIGFwcGxpZWQgZnVsbHkKKyAgdG8gdGhlIGdlbmVyYXRlZCBIVE1MLgorICAt LT4KKzx4c2w6dGVtcGxhdGUgbmFtZT0iYm9keS5hdHRyaWJ1dGVzIj4KKyAgPHhzbDphdHRy aWJ1dGUgbmFtZT0iaWQiPmRvY0NvbnRlbnQ8L3hzbDphdHRyaWJ1dGU+CisgIDx4c2w6YXR0 cmlidXRlIG5hbWU9ImNsYXNzIj5jb250YWluZXItZmx1aWQgY29sLTEwPC94c2w6YXR0cmli dXRlPgorPC94c2w6dGVtcGxhdGU+CiAKIDwhLS0gQ2hhbmdlIGRpc3BsYXkgb2Ygc29tZSBl bGVtZW50cyAtLT4KIApkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL3N0eWxlc2hlZXQueHNs IGIvZG9jL3NyYy9zZ21sL3N0eWxlc2hlZXQueHNsCmluZGV4IDRmZjZlOGVkMjQuLmJjNWE5 MDRlMGIgMTAwNjQ0Ci0tLSBhL2RvYy9zcmMvc2dtbC9zdHlsZXNoZWV0LnhzbAorKysgYi9k b2Mvc3JjL3NnbWwvc3R5bGVzaGVldC54c2wKQEAgLTIzLDExICsyMywxNSBAQAogPHhzbDpw YXJhbSBuYW1lPSJodG1sLnN0eWxlc2hlZXQiPgogICA8eHNsOmNob29zZT4KICAgICA8eHNs OndoZW4gdGVzdD0iJHdlYnNpdGUuc3R5bGVzaGVldCA9IDAiPnN0eWxlc2hlZXQuY3NzPC94 c2w6d2hlbj4KLSAgICA8eHNsOm90aGVyd2lzZT5odHRwczovL3d3dy5wb3N0Z3Jlc3FsLm9y Zy9tZWRpYS9jc3MvZG9jcy5jc3M8L3hzbDpvdGhlcndpc2U+CisgICAgPHhzbDpvdGhlcndp c2U+CisgICAgICBodHRwczovL3d3dy5wb3N0Z3Jlc3FsLm9yZy9tZWRpYS9jc3MvZm9udGF3 ZXNvbWUuY3NzCisgICAgICBodHRwczovL3d3dy5wb3N0Z3Jlc3FsLm9yZy9tZWRpYS9jc3Mv Ym9vdHN0cmFwLm1pbi5jc3MKKyAgICAgIGh0dHBzOi8vd3d3LnBvc3RncmVzcWwub3JnL21l ZGlhL2Nzcy9tYWluLmNzcworICAgICAgaHR0cHM6Ly93d3cucG9zdGdyZXNxbC5vcmcvbWVk aWEvY3NzL25vcm1hbGl6ZS5jc3MKKyAgICA8L3hzbDpvdGhlcndpc2U+CiAgIDwveHNsOmNo b29zZT4KIDwveHNsOnBhcmFtPgogCi0KIDwhLS0gc3RyaXAgZGlyZWN0b3J5IG5hbWUgZnJv bSBpbWFnZSBmaWxlcmVmcyAtLT4KIDx4c2w6dGVtcGxhdGUgbWF0Y2g9ImltYWdlZGF0YS9A ZmlsZXJlZiI+CiAgPHhzbDp2YWx1ZS1vZiBzZWxlY3Q9InN1YnN0cmluZy1hZnRlciguLCAn LycpIi8+Cg== --------------F5B811F65618A6991F78566B-- --1HZsa0ZvQF1mRgpl69naZdXoGVN2A8dwz-- --RFhRElG9qZCLUkkLm4WLTQu7aEqcR40sD Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl5HIq0ACgkQ8QSccp8c ZSdpag//Ws0DmTh//d/KmFC2yhhxO6wQFHcz6VKwctb+dmpbA133pnScPnpYMF/x Qj7JwUchIvAC0XC41qLIYJUqtXeefnJgpWGqOqSTEx3+vT829Wb5zvN3tD2DOZeW Kl1fJ6ewfGrs9X0eVnk3lqD76HXzyACL7KPmjn7TybCRmvN9U6AQvOWaZGv4LHQd QBV8qeuf/zu+iMy+KCM6BmXe811CU/S195xlSH1f19U7H6voDvvdN1ggz316kUBY PQZ+EQ1J1vdDO/n7mqkSVIJgN9nyHFIJobf+Kl9kIrBlSECpdAehc1iY9FrvXYTI oTa33mEB2SQwVBvvBQTAo+pdUvqyx0hRBzf+is+KiRyRWaNj1oDN4dGOC2qdJtV/ AUOpwh0y/8+X4qhXn+R2vv+7D/8YOC33wzNyh0GT6z6oU/+wujwxXYR9sxljMYUs qHlv5aJgCaXVVw3nCorlVbFdhwxddlzBflAsyMrrMg1NuLm1q1osf9KUyfr51Q3/ 0KBAQgCK6kDs39/xrCmo0sFz9Giap0BNkyBxXUi8gjQwpn68V7RlWKsaYid+GfXA YO+syfx5LanlBzCI/opC4F5BM52+R3GUdylQVBs7Zzg6GseWo5mbHNIE//BD1vhd JQrrClHWkGQCiJrY+sLAlfb2pXu2npjosvi16jw5PmHEn882VTo= =Xyhl -----END PGP SIGNATURE----- --RFhRElG9qZCLUkkLm4WLTQu7aEqcR40sD--