Documentation in pdf format

[Geert Janssens]

On Thursday 25 November 2010, Cristian Marchi wrote:
> I've experimented a little with the pdf image size issue and I've found
> a solution. Fop is printing-oriented so it doesn't consider the image
> size but the pixel-per-inch (ppi) attribute. So if the image has a ppi
> of 72 (as normally is when saving an image file) and a width of 510pixel
> it will be printed with a width of 510/72*2,5=17,7cm.
I figured it had to something along those lines. Thanks for fully clearing 
this up !

> At this point I
> figured out a simple way to convert all the images ppi in a run with
> Imagemagik:. From the figures folder issue the following two commands:
> 
> ls *.png > list
> for i in `cat list`; do convert -units PixelsPerInch -density 130 "$i"
> "$i"; done
> 
> The best would be to have the ppi changed or (checked) automatically
> when "make pdf" is issued (I don't know how to do this). If the check is
> on user-side there will be the need of a new dependency (imagemagick) so
> I think it would be better to have a check upstream.
> 
A check upstream would definitly make sense to guarantee a minimum ppi before 
checking in images. I think it has to be a check though, and leave it to the 
contributor to actually set the desired ppi. It can't be less than the minimum 
ppi, but it may be more in some circumstances.

Now that we have on-screen and printed media output, I think we may have to 
reconsider our image handling slightly.

For good print results the more image detail available the better. Our on-
screen process limits images to 510 pixels for comfortable viewing on small 
screens. For this reason, many screenshot are resized to fit this 510 pixel 
constraint. This means the images are also resized before they are put into 
pdf, or in other words they have less image detail than they could have, which 
reduces the print quality.

So I would propose to no longer resize the original screenshots in the 
documentation source, but do the resizing only as part of the on-screen (html) 
output production when needed. This can be easily done with forementioned 
imagemagick.

This would give us the best in both worlds: better quality images for pdf and 
images that still fit the limited space requirements in html.

We'd have to double-check if this added dependency is ok on all platforms of 
course. I know it's is readily available on all distributions, and there is a 
Windows binary we can download straight away. There is also a macports binary 
available on OSX, but I'm not sure if that would be sufficient for John's 
native Quartz build or the fink build. But I found that on OS X the native 
command line utility sips [1] could be used to achieve the same thing. 

> So we need only to choose in what dimension print images in PDF and set
> a ppi to all figures.
> 
From an unrelated project I did yesterday in Scribus, I learned that Scribus 
issues a warning if the resolution of images is less that 144dpi when 
exporting to pdf. So apparently, 144dpi is some generally accepted minimum to 
have a decent print quality. I propose to use that as ppi voor all images that 
don't have a higher ppi set already.

> 
> NOTE: the ppi attribute is not influent on image size but only in it's
> printed size (on paper) and not in video. So changing this attribute is
> like not changing it at all if you display the Manual on your monitor.
> 


[1] 
http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/sips.1.html