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 <jkatz@postgresql.org> wrote:
>>>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>>>> 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 lack
>>>>> 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.
>>>
>>> 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=website 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
<xsl:param name="html.stylesheet">
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=website 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.stylesheet.html
