-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] 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 +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com