Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk