Re: [boost] Boost.Test documentation update; alpha release

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2007-08-13 23:06:50

"Paul A Bristow" <pbristow_at_[hidden]> wrote in message 
news:003101c7ddc8$50ac1100$0400a8c0_at_hetp7...
> 1  First line 1 space indent is a bit odd - not enough to be a real 
> indent.
> 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 
> too).

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 
> macros
>
> 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 
reference section.

> 12 You could help the ignorant (eg me) with a link
>
> [@http://en.wikipedia.org/wiki/Buridan's_ass Buridan's donkey]

OK

> 13  MS .net specific "jump through these errors using usual keyboard 
> shortcuts/mouse clicks you use for compilation error annalists"
> Spelling
> mistake 'analysis'

fixed

> 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
>
> "$(TargetDir)\$(TargetName).exe"
>
> 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 [1]  [2] ... 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.

Gennadiy