Boost logo

Boost :

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
>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)?
>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 A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
+44 1539561830 & SMS, Mobile +44 7714 330204 & SMS

Boost list run by bdawes at, gregod at, cpdaniel at, john at