Subject: [Boost-docs] [quickbook] [style] adjusting the text column width
From: Julian Gonggrijp (j.gonggrijp_at_[hidden])
Date: 2011-03-26 19:21:30
Dear Boost documentation experts,
I've been informing myself a bit about the standardized Boost methods
for writing documentation, and QuickBook seems to be just the right
thing for me. However, for future use in Boost documentation I'm
concerned about something that also troubles me in existing Boost
documentation: the way in which the body text is (not) wrapped by the
standard Boost stylesheet.
In various situations, including in Boost code and the Boost mailing
lists, there are guidelines that suggest to make text columns no wider
than about 70 or 80 characters. An often cited argument for such
guidelines is that other people might have narrow screens and thence
text columns shouldn't be too wide to assure proper, comfortable
rendering on their machines.
There is however another, even more important reason for such
guidelines which applies to any screen width. Human readability is
best when text columns contain no more than about 66 printing
characters (so that's 70-75 characters including whitespace). This is
also the reason that LaTeX documents seem to have rather wide side
margins on A4 format or American letter format, and the reason that
magazines and newspapers print on multiple columns.
Web browser windows (including mine) tend to be wider than this ~75
character limit in order to accomodate websites that use multi-column
layouts and the like. If a stylesheet of a one-column layout, like the
BoostBook stylesheet, doesn't take this into consideration text will
be wrapped to the window with and hence be less readable than it could
Users shouldn't be forced to change the window width of their browser
just because some website refuses to restrain the text column width.
So to conclude my somewhat lengthy argumentation, I have a question
about the CSS support in QuickBook which is mentioned at the first
page of the QuickBook documentation. How to go about constraining the
column width? Is there an easy way to add some CSS to the
documentation, while keeping everything else from the Boost
stylesheets (and without needing to dig into every output html file
every time)? I couldn't find the answer to this question in the
QuickBook documentation, nor in the BoostBook documentation.
At the option of the maintainers, this email may also be considered a
request for a permanent change to the Boost stylesheets, because I
think all Boost documentation would improve considerably if the column
width were constrained to about 80en or about 600px.
Thank you for your patience and kind regards,
This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC