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>
 <86f03290-e60c-855e-786a-d1b75c254811@postgresql.org>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Message-ID: <716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org>
Date: Wed, 12 Feb 2020 08:15:08 -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: <86f03290-e60c-855e-786a-d1b75c254811@postgresql.org>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="I7qkGF2L0NU0mDantUjuN6lWBpl8b1qba"
Precedence: bulk

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

--d2eabd0UWZwS1UFQjC8EyhouJalqSLbej
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

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.o=
rg> wrote:
>>>> Anyway, attached is a first attempt at a patch. I tried a few differ=
ent
>>>> 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 la=
ck
>>>> 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. I=
t
>>> 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.
>=20
> 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:
>=20
> As I mentioned, the way pgweb works is that it wraps a root element (th=
e
> <div id=3D"docContent">...</div>) around the imported HTMl from the
> generation, which allows it to apply the various website styles. This i=
s
> important, because it allows us to apply some general style rules, but
> namespace them specifically to the documentation. Hold this thought for=

> a moment.
>=20
> When calling "make STYLE=3Dwebsite html", this turns on a flag that emb=
eds
> 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 ou=
r
> 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 CS=
S
> rules still expect there to be the #docContent namespace.
>=20
> I thought this would be a good area to explore to see if I could get th=
e
> #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).
>=20
> This works with pgweb as pgweb extracts the content from the <body> tag=

> that is generated by "make html" so this is unaffected.
>=20
> 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).
>=20
> 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 o=
n
> 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.
>=20
> 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=3Dwebsite and it should now look better.

Thanks,

Jonathan


--d2eabd0UWZwS1UFQjC8EyhouJalqSLbej--

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

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

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl5D+lwACgkQ8QSccp8c
ZScjLA//RnDjH+T2Lydi/D0u4YZ5QFzp1XADG2EkGN95wORFFbPuT15VNbr3xGif
NCVPs7GUaH58rbJbLx/co+GbfvWdk/MFw+rBlDr65t2WUw54awbGGyO6pgi74fp+
4HMfgLgH4KZjYseWmcMk1hdZGElSPY018wDr8bB3QmHFF0pttSdquvy8Sk0dgMP1
kGHVNVIYsi9xzETSEWaCbWKrFiE6+DGvHeWItHxLm6iT7T5/5qz0dtvIF8veQG+i
X8JkyagLI3GltB/d+CKJih70OoUYQhG7OvVMLgt70sqpk3/eNFVgWyxLfPC1x8D/
DGlo7Hc2pjJb8stkBX9YoashM+e/UKvgWKO7H8SjeYNxVBXwd4ry+p5xUWj+A7EN
9c1tkb10m9w0Hc4+JIqL5hrpsA3X3nClp1VMKgTZsyRUzA1HRCB9jcGe8Vi/4y+i
75nSF3sQIiiNy1KMRyztAugZAX2IjXRteySfe7Q78KFzi1oZPv/LEwPSPNTt5+++
7SvlcRrjIvyBp/kE7110nJJIfjJiWIJ+SYpDB+4OLG6hGLR10J3VgcGhZm2G+U8o
EFhzCNybj5pgH88fJVe0zqltfS0RZ35exKrwqPWOOBMYtMiWC1kwSBBTYirdzv6F
iLiQT3hvveQaXemHISwhMcEhkBPunXXtq1WZ+yokqqM0/znQT/k=
=mqZu
-----END PGP SIGNATURE-----

--I7qkGF2L0NU0mDantUjuN6lWBpl8b1qba--