Small issue in online devel documentation build

On Thu, Feb 16, 2017 at 1:05 PM, Fabien COELHO <coelho@cri.ensmp.fr> wrote:

When consulting the online "devel" documentation, for instance for
"pgbench":

https://www.postgresql.org/docs/devel/static/pgbench.html

Unordered lists <ul> are shown in bold, as can be seen in the -M option and
in the description of random functions. This is because "ul" is in class
"c2" in the html:

<ul class="itemizedList c2"> ...

I cannot reproduce this when generating html for head, so I gather that the
web-site doc generation must be based on a different transformations.

My point is that some xsl file should be fixed somewhere, probably, to avoid
that.

Yeah, I noticed this too, and I think Ashutosh also complained about
it on another thread. It's pretty annoying - I hope somebody can
figure out the cause and fix it. It seems to be only affecting the
development docs.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

My point is that some xsl file should be fixed somewhere, probably, to avoid
that.

Yeah, I noticed this too, and I think Ashutosh also complained about
it on another thread. It's pretty annoying - I hope somebody can
figure out the cause and fix it. It seems to be only affecting the
development docs.

My 0.02€:

After some random digging, it seems that the documentation files are
loaded from provided tarballs by a script: "tools/docs/docload.py"
maintained in "pgweb.git". Maybe this is run from some cron.

AFAICS from the script, the provided tarballs contains the generated html
that someone/something has already generated and put somewhere. I have
found no clear clue about who, where and when. However I would bet that
"Magnus Hagander" and "Dave Page" know, given that they commits suggest
that they are maintaining the site:-)

The load script passes the doc through "tidy" with some options, and
registers the pages into a database probably for django. I doubt this
would change the ul class.

--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 2/16/17 15:35, Fabien COELHO wrote:

After some random digging, it seems that the documentation files are
loaded from provided tarballs by a script: "tools/docs/docload.py"
maintained in "pgweb.git". Maybe this is run from some cron.

AFAICS from the script, the provided tarballs contains the generated html
that someone/something has already generated and put somewhere. I have
found no clear clue about who, where and when. However I would bet that
"Magnus Hagander" and "Dave Page" know, given that they commits suggest
that they are maintaining the site:-)

The load script passes the doc through "tidy" with some options, and
registers the pages into a database probably for django. I doubt this
would change the ul class.

Can someone from the web site team look into this?

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

On Sat, Feb 18, 2017 at 1:45 AM, Peter Eisentraut <
peter.eisentraut@2ndquadrant.com> wrote:

On 2/16/17 15:35, Fabien COELHO wrote:

After some random digging, it seems that the documentation files are
loaded from provided tarballs by a script: "tools/docs/docload.py"
maintained in "pgweb.git". Maybe this is run from some cron.

AFAICS from the script, the provided tarballs contains the generated html
that someone/something has already generated and put somewhere. I have
found no clear clue about who, where and when. However I would bet that
"Magnus Hagander" and "Dave Page" know, given that they commits suggest
that they are maintaining the site:-)

The load script passes the doc through "tidy" with some options, and
registers the pages into a database probably for django. I doubt this
would change the ul class.

Can someone from the web site team look into this?

Sure.

The script in question loads the docs from the build tarballs - we read
whatever goes in the snapshot tarballs on the site and load that in the db.

The developer docs, and the snapshot tarballs, run as a final step of the
buildfarm job on guaibasaurus.

The toolchain used previously (9.6) generates this code:
<P

Protocol to use for submitting queries to the server:

<P

</P
</P><UL
<LI
<P
<TT

CLASS="LITERAL"

simple</TT
: use simple query protocol.</P
</LI
<LI
<P
<TT

CLASS="LITERAL"

extended</TT
: use extended query protocol.</P
</LI
<LI
<P
<TT

CLASS="LITERAL"

prepared</TT
: use extended query protocol with prepared statements.</P
</LI
</UL

(yes, including all the horrible newlines in the middle of tags and
whatnot, but there's nothing new about that)

The toolchain used for dev (10) generates this code:
<p> Protocol to use for submitting queries to the server:
</p><div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem"><p><code
class="literal">simple</code>: use simple query protocol.</p></li><li
class="listitem"><p><code class="literal">extended</code>: use extended
query protocol.</p></li>

So the HTML generated is completely different. The old one didn't even use
unnumbered lists.

Is that intentional?

I for one did not realize the new toolchain created completely different
structure HTML. I know we applied a41a4cc74be8c34f7f8f1c4ec03b5dc01db06c17
to handle changes from the new toolchain, but that won't cover cases where
the whole structure is different.

In this particular case, the boldness comes from the c2 class as indicated
earlier. But that class has always been bold.

Might it just be that somebody has to actually go over the new structure of
the docs and provide the appropriate CSS rules? Or is something wrong with
the actual building of them as they give a completely different structure?

As for the reproduction - the snapshot tarballs are built by the buildfarm
animal guaibasaurus, which is on Debian Jessie. Could the inability to
reproduce be because of platform differences in the docs tools?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Hello Magnus,

The toolchain used previously (9.6) generates this code:
<UL

<LI
<P
<TT

CLASS="LITERAL"

simple</TT
: use simple query protocol.</P

[...]

(yes, including all the horrible newlines in the middle of tags and
whatnot, but there's nothing new about that)

Yes this is the "old" html generation with jade, which has been replaced
by some xsltproc-based html generation. Why not.

The toolchain used for dev (10) generates this code:

<p> Protocol to use for submitting queries to the server:
</p><div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem"><p><code
[...]

Yes, that the output I also have, which is somehow fine although verbose.
In particular, there is no "c2" class involved in "ul" above...

So the HTML generated is completely different. The old one didn't even use
unnumbered lists.

??? AFAICS there is a <UL> in the first 9.6 extract above... the
difference is about the added class, style & div... but the structure
seems to be basically the same.

I for one did not realize the new toolchain created completely different
structure HTML. I know we applied a41a4cc74be8c34f7f8f1c4ec03b5dc01db06c17
to handle changes from the new toolchain, but that won't cover cases where
the whole structure is different.

I'm not sure it is that different, but there seems to be side effect at
some stages when the doc files are integrated into the web site.

In this particular case, the boldness comes from the c2 class as indicated
earlier. But that class has always been bold.

Probably. The question is rather why is the ul in this class on the
website, while it is not in the raw generated file? What adds it?

Might it just be that somebody has to actually go over the new structure of
the docs and provide the appropriate CSS rules? Or is something wrong with
the actual building of them as they give a completely different structure?

I'm unsure about "completely different", see above.

As for the reproduction - the snapshot tarballs are built by the buildfarm
animal guaibasaurus, which is on Debian Jessie. Could the inability to
reproduce be because of platform differences in the docs tools?

I regenerated the 10 doc on a jessie host with the new xsltproc-based
toolchain and got the same result as what you outline above, in particular
no mention of "c2".

So my guess is that it would be enough not to add this c2 class to ul to
avoid boldness.

Now the actual web pages is clearly a reprocessing of the generated xml,
so this c2 get added between the raw xhtml documentation that one can
reproduce and the web-page xml where there are specific headers for
navigation, as well as some heavy reindentation.

The script on pgweb.git suggest that a "tidy" thing is called on the xml
which is probably responsible for the reindentation, but maybe there are
other xslt or misc tools involved which are not accessible and contribute
to the final result?

--
Fabien.

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

On Sat, Feb 18, 2017 at 1:44 PM, Fabien COELHO <coelho@cri.ensmp.fr> wrote:

Hello Magnus,

The toolchain used previously (9.6) generates this code:

<UL

<LI
<P
<TT

CLASS="LITERAL"

simple</TT
: use simple query protocol.</P

[...]

(yes, including all the horrible newlines in the middle of tags and
whatnot, but there's nothing new about that)

Yes this is the "old" html generation with jade, which has been replaced
by some xsltproc-based html generation. Why not.

The toolchain used for dev (10) generates this code:

<p> Protocol to use for submitting queries to the server:
</p><div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem"><p><code
[...]

Yes, that the output I also have, which is somehow fine although verbose.
In particular, there is no "c2" class involved in "ul" above...

Ah, that is correct. I thought I could see it there, but turns out that no,
I cannot :) I was clearly not awake. My apologies.

It turns out the "c2" class is added by tidy. The reason is this:
http://api.html-tidy.org/tidy/quickref_5.0.0.html#clean

There was a reason this was needed on the old docs. I honestly don't
remember what it was though, but it was needed (but many things were needed
on that source).

Turning if off makes that page work. It might break pages elsewhere though.

I've removed the flag for the devel docs build for now (or - for any XML
based docs build). I've also forced another docs load, so the results can
be checked.

Let's see if that breaks something else...

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Hello Magnus,

It turns out the "c2" class is added by tidy. The reason is this:
http://api.html-tidy.org/tidy/quickref_5.0.0.html#clean

I've removed the flag for the devel docs build for now (or - for any XML
based docs build). I've also forced another docs load, so the results can
be checked.

Indeed, thanks, now it looks great... under firefox at least.

Another issue in the new HTML documentation, this time not related to the
web site. Under chrome there are some strange font size effects on
options, for instance with this HTML in "app-psql.html":

<span class="term">
<code class="option">-f
<em class="replaceable"><code>filename</code></em>
</code>
<br>
</span>

For previous versions, the following html was generated:

<tt class="OPTION">-f <tt class="REPLACEABLE c2">filename</tt></tt>

The filename in the newer html appears much larger under chrome, seemingly
because of the <code> within a <code>. Maybe a bug in chrome CSS
interpretation, because CSS on code seems to indicate "font-size: 1.3em",
but it seems to do 1.3**2 instead for "filename"... However it does not do
that elsewhere so it may not be that simple...

Basically it looks ok under chrome if in the initial sgml file there is:

<term><option>-s</option> <replaceable>scale_factor</></term>

(replaceable is out of option)

But bad on:

<term><option>--tablespace=<replaceable>tablespace</replaceable></option></term>

(replaceable is in the option), because the size change is somehow applied
twice.

The docbook doc says that "replaceable" is a children of "option", which
seems to suggest that this nested usage is legit... but it may be buggy as
well.

This may be fixed/worked around in several places:

1. html generation could be clever enough not to nest "code" tags?
or generate tt tags instead as was done before?

I have not found where this transformation is defined, probably
somewhere within "docbook"...

2. avoid replaceable within option in initial sgml files
=> many changes, will reappear if someone forgets.

3. some more post-processing tidying could be done
hmmm:-(

4. chrome should be repaired if there is indeed a bug...

--
Fabien.

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

<span class="term">
<code class="option">-f
<em class="replaceable"><code>filename</code></em>
</code>
<br>
</span>

The filename in the newer html appears much larger under chrome, seemingly
because of the <code> within a <code>. Maybe a bug in chrome CSS
interpretation, because CSS on code seems to indicate "font-size: 1.3em", but
it seems to do 1.3**2 instead for "filename"... However it does not do that
elsewhere so it may not be that simple...

2. avoid replaceable within option in initial sgml files
=> many changes, will reappear if someone forgets.

I wrote a few lines of perl to move replaceable out of option and did some
manual editing is special cases, the resulting simple 359 changes is
attached.

--
Fabien.

On 2/19/17 12:34, Fabien COELHO wrote:

I wrote a few lines of perl to move replaceable out of option and did some
manual editing is special cases, the resulting simple 359 changes is
attached.

If the stylesheet produces unpleasant output, then the stylesheet should
be changed.

The current markup looks fine (to me) with the minimal default/non-web
stylesheet, so the issue is somewhere else.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hello Peter,

I wrote a few lines of perl to move replaceable out of option and did some
manual editing is special cases, the resulting simple 359 changes is
attached.

If the stylesheet produces unpleasant output, then the stylesheet should
be changed.

Sure.

I'm not sure whether it is a stylesheet issue: it is the stylesheet as
interpreted by chrome... all is fine with firefox. Whether the bug is in
chrome or the stylesheet or elsewhere is well beyond my HTML/CSS skills,
but I can ask around.

The current markup looks fine (to me) with the minimal default/non-web
stylesheet, so the issue is somewhere else.

Attached how "Google Chrome 56.0.2924.87 (Official Build) (64-bit)" on my
ubuntu laptop shows the options in of the psql dev doc using the online
css.

--
Fabien.

I'm not sure whether it is a stylesheet issue: it is the stylesheet as
interpreted by chrome... all is fine with firefox. Whether the bug is in
chrome or the stylesheet or elsewhere is well beyond my HTML/CSS skills, but
I can ask around.

After asking around, and testing with a colleague, we got the same
strange size behavior on firefox mac as well.

There are 2 possible solutions:

(1) do not nest in the first place (i.e. apply the patch I sent).

(2) do use absolute sizes in the CSS, not relative ones like "1.3em"
which accumulate multiplications when code appears in code,
and count on the navigator ctrl-+/- for users to adjust size
consistently to their needs.

--
Fabien.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

After asking around, and testing with a colleague, we got the same strange
size behavior on firefox mac as well.

There are 2 possible solutions:

(1) do not nest in the first place (i.e. apply the patch I sent).

(2) do use absolute sizes in the CSS, not relative ones like "1.3em"
which accumulate multiplications when code appears in code,
and count on the navigator ctrl-+/- for users to adjust size
consistently to their needs.

(3) a CSS work-around, including the "!important" marker:

code code {
font-size: 100% !important;
}

This is probably the minimum fuss solution.

--
Fabien.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 3/2/17 05:50, Fabien COELHO wrote:

(2) do use absolute sizes in the CSS, not relative ones like "1.3em"
which accumulate multiplications when code appears in code,
and count on the navigator ctrl-+/- for users to adjust size
consistently to their needs.

I think what you are looking at is the web site stylesheet. The whole
thing looks fine to me using the default stylesheet. On the web site,
it looks wrong to me too. I don't know what the rationale for using
1.3em for <code> is, but apparently it's not working correctly.

We could perhaps consider which markup style is better, but the problem
is that it's hard to enforce either way going forward. So we need to
find the root of the problem.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hello Peter,

I think what you are looking at is the web site stylesheet.

Yep.

The whole thing looks fine to me using the default stylesheet. On the
web site, it looks wrong to me too. I don't know what the rationale for
using 1.3em for <code> is, but apparently it's not working correctly.

Indeed. The idea of relative size is to be able to adjust the size for the
whole page and have everything scale accordingly... however this mostly
works well with text, but not with images. It seems that the trend is now
to specify absolute size, and to let the browser do whole page scaling as
required by the user.

We could perhaps consider which markup style is better, but the problem
is that it's hard to enforce either way going forward. So we need to
find the root of the problem.

The root of the problem is the combination of relative size & nesting, so
one or the other has to be removed:

(1) don't nest in the input (patch I sent)
(2) don't use relative sizes (update the web site CSS)

Otherwise there are workarounds:

(3) CSS work around "code code { font-size: 100% !important; }"
(4) unnest code in the output by some postprocessing or some more
clever transformation.

--
Fabien.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Web team, any thoughts on the CSS details?

On 3/4/17 02:00, Fabien COELHO wrote:

Hello Peter,

I think what you are looking at is the web site stylesheet.

Yep.

The whole thing looks fine to me using the default stylesheet. On the
web site, it looks wrong to me too. I don't know what the rationale for
using 1.3em for <code> is, but apparently it's not working correctly.

Indeed. The idea of relative size is to be able to adjust the size for the
whole page and have everything scale accordingly... however this mostly
works well with text, but not with images. It seems that the trend is now
to specify absolute size, and to let the browser do whole page scaling as
required by the user.

We could perhaps consider which markup style is better, but the problem
is that it's hard to enforce either way going forward. So we need to
find the root of the problem.

The root of the problem is the combination of relative size & nesting, so
one or the other has to be removed:

(1) don't nest in the input (patch I sent)
(2) don't use relative sizes (update the web site CSS)

Otherwise there are workarounds:

(3) CSS work around "code code { font-size: 100% !important; }"
(4) unnest code in the output by some postprocessing or some more
clever transformation.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

On Fri, Mar 10, 2017 at 11:21:33AM -0500, Peter Eisentraut wrote:

Web team, any thoughts on the CSS details?

I think I did some CSS long ago to adjust font sizes for certain font
types on our website. Should I find that?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

Hello Bruce,

On Fri, Mar 10, 2017 at 11:21:33AM -0500, Peter Eisentraut wrote:

Web team, any thoughts on the CSS details?

I think I did some CSS long ago to adjust font sizes for certain font
types on our website. Should I find that?

Dunno. Maybe?

The issue is the 1.3em associated to code, because when code is used
within code, the 1.3 multiplier accumulates and things get bigger and
bigger.

Now the font size fixing is a good thing because courrier like fonts are
somehow too small, it just must not accumulate, hence the suggested
solutions, one of which should be applied.

--
Fabien.

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

On Sat, Mar 11, 2017 at 07:04:06AM +0100, Fabien COELHO wrote:

Hello Bruce,

On Fri, Mar 10, 2017 at 11:21:33AM -0500, Peter Eisentraut wrote:

Web team, any thoughts on the CSS details?

I think I did some CSS long ago to adjust font sizes for certain font
types on our website. Should I find that?

Dunno. Maybe?

The issue is the 1.3em associated to code, because when code is used within
code, the 1.3 multiplier accumulates and things get bigger and bigger.

Now the font size fixing is a good thing because courrier like fonts are
somehow too small, it just must not accumulate, hence the suggested
solutions, one of which should be applied.

OK, it was Javascript, not CSS. Here is what I think I did to fix the
fonts:

https://github.com/postgres/pgweb/blob/master/media/js/monospacefix.js

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www

Now the font size fixing is a good thing because courrier like fonts are
somehow too small, it just must not accumulate, hence the suggested
solutions, one of which should be applied.

OK, it was Javascript, not CSS. Here is what I think I did to fix the
fonts:

https://github.com/postgres/pgweb/blob/master/media/js/monospacefix.js

Indeed, this javascript does generates the faulty display based on a
dynamic evaluation of relative font sizes. That's fun.

Maybe just generate a fixed size instead so as to avoid accumulation on
nesting?

--
Fabien.

--
Sent via pgsql-www mailing list (pgsql-www@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-www