Boost.Test documentation update; alpha release
Hi, I've finally been able to produce alpha release of completely reworked BoostBook based documentation for Boost.Test library. It's still not ready for release and I expect significant changes in both L&F (once I apply latest IBD based style) and content (some articles still missing). But it's in a shape close to what I would like it to be. I would really appreciate any comments to both content (language including) and style. I realize it might not be small undertaking so if you have time for just part of it, please post comments as well. The release is available here: patmedia.net/~rogeeff/html/index.html in patmedia.net/~rogeeff/src you can find sources. Thank you, Gennadiy
Gennadiy Rozental wrote:
Hi,
I've finally been able to produce alpha release of completely reworked BoostBook based documentation for Boost.Test library. It's still not ready for release and I expect significant changes in both L&F (once I apply latest IBD based style) and content (some articles still missing). But it's in a shape close to what I would like it to be.
I would really appreciate any comments to both content (language including) and style. I realize it might not be small undertaking so if you have time for just part of it, please post comments as well.
The release is available here:
patmedia.net/~rogeeff/html/index.html
Looks nice, I did notice: #include <execution_monitor.hpp> which is surely not correct? Should it be #include <boost/test/execution_monitor.hpp> ? Also from a quick look through I had trouble finding the section I most use: the test macro reference. I eventually found http://patmedia.net/~rogeeff/html/utf/testing-tools/reference.html, some kind of overview of the test macros available would be very helpful IMO (or maybe I missed it?), as this is basically the "meat" of the library. I'm not sure how that reference page would work as a PDF either? HTH, John.
"John Maddock" <john@johnmaddock.co.uk> wrote in message news:00c201c7dcc5$799e6440$14120952@fuji...
Gennadiy Rozental wrote:
Hi,
I've finally been able to produce alpha release of completely reworked BoostBook based documentation for Boost.Test library. It's still not ready for release and I expect significant changes in both L&F (once I apply latest IBD based style) and content (some articles still missing). But it's in a shape close to what I would like it to be.
I would really appreciate any comments to both content (language including) and style. I realize it might not be small undertaking so if you have time for just part of it, please post comments as well.
The release is available here:
patmedia.net/~rogeeff/html/index.html
Looks nice, I did notice:
#include <execution_monitor.hpp>
which is surely not correct? Should it be #include <boost/test/execution_monitor.hpp> ?
fixed
Also from a quick look through I had trouble finding the section I most use: the test macro reference. I eventually found http://patmedia.net/~rogeeff/html/utf/testing-tools/reference.html,
How would you like me to make it easier to find?
some kind of overview of the test macros available would be very helpful IMO (or maybe I missed it?), as this is basically the "meat" of the library.
Doesn't this page http://www.patmedia.net/~rogeeff/html/utf/testing-tools.html fit the bill?
I'm not sure how that reference page would work as a PDF either?
I plan to use regular boostBook like reference. I am not planning to support PDF output in first cut. Gennadiy
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 12 August 2007 10:27 To: boost@lists.boost.org Cc: boost-users@lists.boost.org; boost-docs@lists.boost.org Subject: [boost] Boost.Test documentation update; alpha release
Hi,
I've finally been able to produce alpha release of completely reworked BoostBook based documentation for Boost.Test library. It's still not ready for release and I expect significant changes in both L&F (once I apply latest IBD based style) and content (some articles still missing). But it's in a shape close to what I would like it to be.
I would really appreciate any comments to both content (language including) and style. I realize it might not be small undertaking so if you have time for just part of it, please post comments as well.
The release is available here:
patmedia.net/~rogeeff/html/index.html
in patmedia.net/~rogeeff/src you can find sources.
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. 2 No icons for navigation - but perhaps they will appear when in the right place. 3 You must explain what a UTF is before using the acronym. 4 No Last revised date. This should be added to the TOC automatically? 5 The minimal testing facility supplies it's own ... should its ( it isn't it is, is it!) 6 The code block backgroun in is too dark (and the code font a bit small too). 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? 8 Mention pre-built libraries - bjam never works first time :-( 9 Admonishment Important duplicates on Standalone library compilation. 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 ;-) 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 ! 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" Spelling 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 "$(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. 15 Test progress display is blank. TODO? 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 ;-) 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. 18 Finally IMO it badly needs an index - but we have yet to devise a good method of automatically indexing Quickbook docs. Overall looks and works MUCH nicer - well worth the pain;-) HTH Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:003101c7ddc8$50ac1100$0400a8c0@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
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 14 August 2007 04:07 To: boost@lists.boost.org Subject: Re: [boost] Boost.Test documentation update; alpha release
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:003101c7ddc8$50ac1100$0400a8c0@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?
Well no other Boost docs use first paragraph line indent. And I single character width looks odd to me. I think indents are a bit last year ;-) So I would follow the Boost style.
3 You must explain what a UTF is before using the acronym.
It is explained in first paragraphs of user's guide.
Ah - but I didn't read that first! And most people will not be too much the wiser on learning it is an acronym for Unit Test Framework either. Assumption is the mother of all misunderstandings. Why Unit they will ask? Why Framework? Of course there are good answers to these things, but they don't want to have to know that - at least yet.
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?
Sorry my joke fell on it's head. I was chiding you for using 'it's' (abbreviation for 'it is') when you should have used 'its'. A common mistake. Rule of thumb - use its and you will more often be right.
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.
I know - I *HATE* it! It's madness - why would you want to make people flick their focus back and forth?
8 Mention pre-built libraries - bjam never works first time :-(
Were? Can you provide exact wording?
" [@http://boost.org/more/getting_started/index.html Boost Getting started] also tells you how to get pre-built libraries for some platforms." If avilable, this is much the easiest option.
9 Admonishment Important duplicates on Standalone library compilation.
Which page? I do not see it.
All the admonishments display for me as [important]Important. But porbably these will disappear when installed in the right place.
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 emphasise it too much.
Well only kinda. You could say "If you find the compile time becoming tiresome, try using linking to a library."
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 about calling it "Test MACROS (BOOST_CHECK*...)" ? or something that doesn't require you to know what UTF stands for.
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
Yours might look like that - Mine has a lime-green background with fuschia characters ;-)) (Just kidding - it's black on white!) A final comment - I think you should take most note of the 'novices' recent comments. I think it is the *structure* that has caused so much grief in the previous version - and that hasn't changed much. You are disadvantaged by having too much knowledge. Users *don't* want it in a logical layout - they *don't* want to know about things they won't use until they have used the basic "add 2 + 2 and check it makes 4" unit test. So make sure the first thing they hit is what they need to know. *Examples* are the quickest way of doing this. The testing the string class is excellent, so make sure that this is what jumps out and hits them. And when they get going, the bit they keep coming back to is the macros, so make sure that hits them too. Good luck! Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
participants (3)
-
Gennadiy Rozental -
John Maddock -
Paul A Bristow