Re: [Boost-docs] Quickbook - Spacing between text and code blocks

Subject: Re: [Boost-docs] Quickbook - Spacing between text and code blocks
From: John Maddock (john_at_[hidden])
Date: 2007-08-16 16:33:47

Paul A Bristow wrote:
> I'm very, very pleased with the overall appearance of Quickbooks
> docs, especially with the new import feature so that much of the text
> can be written into the C++ source - hyper cool!
>
> (If you are not using it yet to write/update your Quickbook docs, you
> should be!)
>
> But I am concerned that the resultant text and code blocks is taking
> a lot of space vertically.
>
> This especially true if you have stuff repeatedly something like
>
> ...
> This is some interesting code that prints hello:
>
>  cout << "Hello" << endl;
>
> Now wasn't that useful?
>
> Now we
>
>  return 0
>
> to say it went OK.
> ...
>
> In essence, there appears to be too much verical space *before* each
> code block outline, and perhaps too much before and after space
> *within* the code block, as well.
>
> The result is that you need to keep scrolling a lot as you read, and
> that it takes a *lot* a paper if you need to print it.
>
> It this something that I/others/readers can/should control?  Do
> others share this impression?

It doesn't bother me much, but...

the problem is that we have (ab)used the code import feature to interweave 
lot's of text and code, rather than having one big code block.  Personally I 
think it's a lot easier to understand the way we've done it, but I guess we 
would almost need two kinds of blocks to achieve what you want: big blocks 
with a border around them, and small blocks with no extra space around them. 
But that complicates things :-(

John.