Re: [pgsql-www] [HACKERS] Small issue in online devel documentationbuild

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.