Documentation xslt stylesheet update and pdf - notes and questions

[Geert Janssens]

To restore the pdf generation functionality, I had to update the xslt 
stylesheet we use to generate the documentation in html format as well.

There were some minor issues to resolve while doing so, but most of it is fine 
now.

Some notes and requests for feedback from the other documentation 
developers/editors:

1. List of figures
The new stylesheet automatically generates a list of figures right below the 
table of contents. However, most of our screenshots are missing from that 
list. This is because the list is generated based on the <figure> tag, while 
most screenshots are inserted with the <screenshot> tag.
I did the experiment in the English help manual to enclose all screenshot tags 
in a figure tag (together with adding a title in the figure tag). This adds 
all the images in the list of figures with the title added.
In most cases I reused the contents of the caption inside the screenshot as 
title. If the caption was too long or elaborate, I chose a shorter title and 
moved the caption outside the figure tag as a normal paragraph. In retrospect, 
the last part may not have been necessary and maybe even unwanted. I don't 
know, what do others think of this ?

Apart from my experiment in the help manual, I have also done the same to a 
couple of screenshots in the English concepts guide. But other than that, this 
whole process still has to be completed for the English concepts guide and the 
other languages.

2. Pdf and images
Unlike html pages, a page in a pdf document has a real and limited width. The 
contents is laid out on this page according to style rules. Some of these 
style rules indent the content (like sections, lists, subsections,...), so 
each content element has a width available that is less than the full page 
width. The deeper the hierarchies or sections, subsections or lists, the 
narrower the available space.
For text this isn't really a problem, as it can be split up on word 
boundaries.
For images, this is another story. By default images are positioned like its 
containing element, so they are more or less offset from the left hand page 
border depending on its position in the hierarchy. In many cases, our 510px 
wide images are too wide to still fit in the available with and the overflow 
off the right hand side of the page. (Fop spews warnings for this).

There is a solution for this: the figure tag has an attribute "pgwide" that 
can be set to "1" to let images be positioned relative to the complete page 
width instead of the current text flow's width. With this attribute set, the 
image will be more to the left relative to the surrounding text, but it does 
fit nicely on the page.

I have experimented with this in the concepts guide. If you generate a pdf for 
r19877 or later, you can compare the accounting equation image in Chapter 2 
with the same image in Chapter 3. The first uses the full page width, the 
later only the width of its context.

For this image the change is an improvement. But I also did the same for the 
images in "Putting it all together" in chapter 2. Some of these images are not 
as wide. You can see here that for more narrow images, the effect may be less 
optimal.

It should be noted that more can be done to the layout than I just did. For 
example, we could center all images on the page. That may improve the effect 
for narrow images again.

What do others think of this ?

3. Pdf and tables
When generating a pdf, you will notice that fop spews a lot of warnings 
regarding tables like this
WARNING: table-layout="fixed" and column-width unspecified => falling back to 
proportional-column-width(1)
This doesn't seem to be critical for the layout, but we may be able to fix the 
warnings by setting some attribute on tables somewhere ?
I haven't investigated this yet, so if someone feels like having a look, just 
go ahead.

Geert