From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2007-08-13 23:06:50
"Paul A Bristow" <pbristow_at_[hidden]> wrote in message
> 1 First line 1 space indent is a bit odd - not enough to be a real
> And anyway I don't think indents help! so I'd go for now indents.
Umm. Why? Isn't it kinda standard?
> 2 No icons for navigation - but perhaps they will appear when in the
> right place.
Yes they point to ../../..../doc/html/...
> 3 You must explain what a UTF is before using the acronym.
It is explained in first paragraphs of user's guide.
> 4 No Last revised date. This should be added to the TOC automatically?
No. It should work onceI put it under source control
> 5 The minimal testing facility supplies it's own ... should its ( it
> isn't it is, is it!)
Sorry, I a bit lost in these "it" and "is". What did you mean?
> 6 The code block backgroun in is too dark (and the code font a bit small
The code will change to match what IBD comes up with.
> 7 I would break up the code and 'inline' the comments. It makes it much
> more difficult to read having to go down to (1), and then
> (2) ... But I'm sure you're tired now ;-) But for future reference...
> (using the code blocks syntax for the code) For example:
> // seven ways to detect and report the same error:
> BOOST_CHECK( add( 2,2 ) == 4 ); // continues on error
> displays an error message (by default on std::cout) that includes the
> expression that failed, the source file name, and the source
> file line number. It also increments an error count. At program
> termination, the error count will be displayed automatically by the
> Unit Test Framework.
> BOOST_REQUIRE( add( 2,2 ) == 4 ); // throws on error
> similar to approach #1, except that after displaying the error, an
> exception is thrown, to be caught by the Unit Test Framework.
> This approach is suitable when writing a explicit test program, and the
> error would be so severe as to make further testing
> impractical. BOOST_REQUIRE differs from the C++ Standard Library's
> assert() macro in that it is always generated, and channels error
> detection into the uniform Unit Test Framework reporting procedure.
> Since this section is what most people want to start with, it would be
> worth splitting it up?
This is not how DocBook based documentation look like usually. Callouts are
located after the source code.
> 8 Mention pre-built libraries - bjam never works first time :-(
Were? Can you provide exact wording?
> 9 Admonishment Important duplicates on Standalone library compilation.
Which page? I do not see it.
> 10 It would help if you said in the Including the UTF directly into your
> test module section that recompilation will *slow down*
> your 'compile, run, crash' cycle ;-)
I kinda saidit with last statement isn't it? The thing is it's not that
significant this days to emphsise it too much.
> 11 It didn't quickly see the thing I need most, most often - a list of the
> BOOST_CHECK ...
> Eventually I found 'The UTF testing tools reference' but only by accident
How do you propose I should make it easier to find? It's testing tools
> 12 You could help the ignorant (eg me) with a link
> [@http://en.wikipedia.org/wiki/Buridan's_ass Buridan's donkey]
> 13 MS .net specific "jump through these errors using usual keyboard
> shortcuts/mouse clicks you use for compilation error annalists"
> mistake 'analysis'
> 14 You've shown using a Post-Build step, but say Use Custom build step.
> I find Thorsten's Custom build step method convenient too with just
> and c:\autorun as the mythical filename.
> This re-runs, even if not rebuilt.
> But perhaps there are advantages to the post-build method too?
> I find that these are rather important convenience features allowing a
> rapid run/test cycle.
I did not play with that one, it's in my TODO list.
> 15 Test progress display is blank. TODO?
Yep. R u up to it?
> 16 I don't like the output in white on black, but taste in 'color' is
> *very* subjective - and some people have no taste at all ;-)
I wanted to mimic regular shell window output
> 17 YOC pages has a number of footnotes/callouts   ... but they
> appear to be orphans - but contain interesting info and the
> links are missing.
Yeah. Some bug in BoostBook. Did not figure it out yet. Looks like they are
all on front page.
> 18 Finally IMO it badly needs an index - but we have yet to devise a good
> method of automatically indexing Quickbook docs.
Yeah. I am thinking about it. I don't use Quickbook though.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk