Re: [boost] Improving PDF generation - a common look and feel?

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-05-08 09:48:50

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of John Maddock
>Sent: 08 May 2007 10:54
>To: Boost mailing list; boost-docs
>Subject: [boost] Improving PDF generation - a common look and feel?

>I've been working on improving our ability to generate PDF's from 
>Quickbook/Docbook source using a "torture-test" consisting of 
>a subset of the Math lib docs. 

>Improving Our Stylesheets
>~~~~~~~~~~~~~~~~~~~~~~~~~
>
>I've made some changes (not committed yet) to our fo.xsl stylesheet to:
>
>* Syntax highlight C++ code.
>* Put a box around code blocks and admonishments.
>* Improve the appearance of tables.
>* Added some keep-together instructions to improve flow-control around 
>tables/code/admonishments.
>
>I've tried to mimic our HTML stylesheets as far possible, and 
>the effects can be seen in the test PDF's.
>
>The Questions:
>~~~~~~~~~~~~~~
>
>1) How do folks feel about the look and feel of these: are 
>these heading in the right direction?

All contribute to overall looking Smart - but :

1] I note that the default page size is US letter.  IMO the ISO Standard A4 would be a better default.  But perhaps this is just my
revenge for all those documents that I have printed with their sides chopped off!

2] My personal preference (and I believe it is common colour scheme) is for comments in green and digits etc in red (keywords in
blue in fine).

3]  The code font is Courier.  Could it be Lucida Console instead - I find this a much more readable fixed width font?  Is this
widely available on non-Windows systems?

4]  Can some of pdf properties - author, title, subject keywords etc be completed automatically.

5]  I note that fast web view is not enabled - many will be reading on screen so this might be useful?

6] Should the document be digitally signed, probably automatically.  Does this have copyright implications?

>2) Do we want a consistent look/feel across all Boost-PDF's?  

Definitely IMO.

>If yes, is it 
>OK to commit the stylesheet changes (diff's attached)?
Yes.
>4) Do we have a consistent location for PDF downloads: if not should we have?

Sounds tidy - alongside html?

Would it make finding documentation easier?  I still feel a TOC is no substitute for an index.

And more important indexing it - one the major problems with Boost documentation is *finding* what you want to know.  Google
provides a useful index, but it is often confusing to use (too many hits, or too few).  Would a Google index of *just the
documentation* be better?  (Or is there too much documentation not in the right place?)

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]