Subject: Re: Duplicating website's formatting in local doc builds
From: "Jonathan S. Katz" <jkatz@postgresql.org>
To: Peter Geoghegan <pg@bowt.ie>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, Pg Docs <pgsql-docs@lists.postgresql.org>
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>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Message-ID: <86f03290-e60c-855e-786a-d1b75c254811@postgresql.org>
Date: Tue, 11 Feb 2020 22:56:27 -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: <dc3089b0-9c40-fc3b-bce1-7fcc16891dd1@postgresql.org>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="8jJjhRk74vEmh14Ur0BABshT8JTNFmdjF"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--8jJjhRk74vEmh14Ur0BABshT8JTNFmdjF
Content-Type: multipart/mixed; boundary="6mO0VgXKnnvM2QvpdVFOh3PsLhH1qN8e6"

--6mO0VgXKnnvM2QvpdVFOh3PsLhH1qN8e6
Content-Type: multipart/mixed;
 boundary="------------380299E5BCE9AA97636EA37B"
Content-Language: en-US

This is a multi-part message in MIME format.
--------------380299E5BCE9AA97636EA37B
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

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.or=
g> wrote:
>>> Anyway, attached is a first attempt at a patch. I tried a few differe=
nt
>>> variations but in my quick review of it, I could not figure out how t=
o
>>> make a XSLT respect having multiple stylesheets (likely due to my lac=
k
>>> of familiarity with XSLT).
>>
>> I tried this patch out.
>=20
> Thanks!
>=20
>> 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
>=20
> Yup, that's a direct result of not having the Bootstrap base.
>=20
>> But even still, it's a vast improvement.
>=20
> 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=3D"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=3Dwebsite html", this turns on a flag that embed=
s
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.htm=
l

--------------380299E5BCE9AA97636EA37B
Content-Type: text/plain; charset=UTF-8; x-mac-type="0"; x-mac-creator="0";
 name="website-formatted-docs-v2.patch"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
 filename="website-formatted-docs-v2.patch"

ZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9zdHlsZXNoZWV0LWh0bWwtY29tbW9uLnhzbCBi
L2RvYy9zcmMvc2dtbC9zdHlsZXNoZWV0LWh0bWwtY29tbW9uLnhzbAppbmRleCA5ZWRjZTUy
YTEwLi44YzJjNzU5YzgxIDEwMDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvc3R5bGVzaGVldC1o
dG1sLWNvbW1vbi54c2wKKysrIGIvZG9jL3NyYy9zZ21sL3N0eWxlc2hlZXQtaHRtbC1jb21t
b24ueHNsCkBAIC0xOCw2ICsxOCwxMyBAQAogPHhzbDpwYXJhbSBuYW1lPSJsaW5rLm1haWx0
by51cmwiPnBnc3FsLWRvY3NAbGlzdHMucG9zdGdyZXNxbC5vcmc8L3hzbDpwYXJhbT4KIDx4
c2w6cGFyYW0gbmFtZT0idG9jLm1heC5kZXB0aCI+MjwveHNsOnBhcmFtPgogCis8IS0tCisg
IFRoZSBiZWxvdyBhbGxvd3MgdGhlIHN0eWxlc2hlZXRzIHByb3ZpZGVkIGJ5IHRoZSB3ZWJz
aXRlIHRvIGJlIGFwcGxpZWQgZnVsbHkKKyAgdG8gdGhlIGdlbmVyYXRlZCBIVE1MLgorICAt
LT4KKzx4c2w6dGVtcGxhdGUgbmFtZT0iYm9keS5hdHRyaWJ1dGVzIj4KKyAgPHhzbDphdHRy
aWJ1dGUgbmFtZT0iaWQiPmRvY0NvbnRlbnQ8L3hzbDphdHRyaWJ1dGU+Cis8L3hzbDp0ZW1w
bGF0ZT4KIAogPCEtLSBDaGFuZ2UgZGlzcGxheSBvZiBzb21lIGVsZW1lbnRzIC0tPgogCmRp
ZmYgLS1naXQgYS9kb2Mvc3JjL3NnbWwvc3R5bGVzaGVldC54c2wgYi9kb2Mvc3JjL3NnbWwv
c3R5bGVzaGVldC54c2wKaW5kZXggNGZmNmU4ZWQyNC4uYmQyN2I4YzFjOSAxMDA2NDQKLS0t
IGEvZG9jL3NyYy9zZ21sL3N0eWxlc2hlZXQueHNsCisrKyBiL2RvYy9zcmMvc2dtbC9zdHls
ZXNoZWV0LnhzbApAQCAtMjMsNyArMjMsNyBAQAogPHhzbDpwYXJhbSBuYW1lPSJodG1sLnN0
eWxlc2hlZXQiPgogICA8eHNsOmNob29zZT4KICAgICA8eHNsOndoZW4gdGVzdD0iJHdlYnNp
dGUuc3R5bGVzaGVldCA9IDAiPnN0eWxlc2hlZXQuY3NzPC94c2w6d2hlbj4KLSAgICA8eHNs
Om90aGVyd2lzZT5odHRwczovL3d3dy5wb3N0Z3Jlc3FsLm9yZy9tZWRpYS9jc3MvZG9jcy5j
c3M8L3hzbDpvdGhlcndpc2U+CisgICAgPHhzbDpvdGhlcndpc2U+aHR0cHM6Ly93d3cucG9z
dGdyZXNxbC5vcmcvZHluY3NzL2RvY3MuY3NzPC94c2w6b3RoZXJ3aXNlPgogICA8L3hzbDpj
aG9vc2U+CiA8L3hzbDpwYXJhbT4KIAo=
--------------380299E5BCE9AA97636EA37B--

--6mO0VgXKnnvM2QvpdVFOh3PsLhH1qN8e6--

--8jJjhRk74vEmh14Ur0BABshT8JTNFmdjF
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl5Dd2sACgkQ8QSccp8c
ZScUmBAAsMWwYZEudW8nXEjBqXeAR7Jx2oWgnX8GeaLwHvzDpH85RSKqoAFtxAlR
N+6Gx9UBAqmcJB6ALNDjCDc83r8QQ29S5jUC73ctxcJfDaNTE8iwf0Fyo+sMRQVi
6C0YUe6w4MEg5VdhgkF/jlzFxkx65zNw/YA+JaGENha2I2V2AQKo0YBkEYKRPpzl
bnH0TFig1liL9AEn4u5il6huUXqgt/Kxbvh7NtNccVaU1RNEWP+RXRosTpBikzeH
OqRrA5T6ilQ2jXOiPwZdi79GTNFcQCJ9xHRk7K2QjmyR1/i3CoDb4l2lc/VOdjEB
VUEczp25Cd1JVdBlheINA694Foy7YC1fmNIBeG1OcQnwcSnxM64Kts7ev5DizsjN
AQ0BGk7yHj6FrZAZavNvqdc+2oLvHEmYtV+rVDoKSxILgAaWq9BiMydTEQkYG+wR
MK4WWlNQdqsmZ+T31j/YjOekfxGqd2qCDn99POkYS6D2x+U6S3rKrkdr825MrMyt
VOXRQmtDWhnfwIyolkSRPA92PkSDGYrvRBxiF2RV4pYmQeH1J2miE3Wp18ZCQcly
OP3GIyRxk0dS9RPB/f/JbvHUx9jPx+sGvXPLshtCPAVC84JkCaaj9NrMBnKC+KNn
f64d33/4qvlHm2UeH5xMI+m33t7i+0+qbPDWW3l1kP3MCzs/hls=
=xkSo
-----END PGP SIGNATURE-----

--8jJjhRk74vEmh14Ur0BABshT8JTNFmdjF--