AMDG Robert Ramey wrote:

Steven Watanabe wrote:

...

AMDG

I'm in the process of updating the Boost.Random documentation. I've put what I have right now at: http://www.cs.hmc.edu/~swatanabe/random_doc/libs/random/doc/html/ The content is mostly the same as the current docs, although I've filled in some missing pieces and fixed some of the more egregious out of date docs. Any comments, criticism, etc, are welcome.

A real improvement.

One nit. Instead of one large file how about a hyper linked hierarchy. For some reason I thought the quick book/docbook generated this automatically.

I believe there's an xsl parameter that can be used to tweak chunking. I'll see if I can get it to split up the reference. In Christ, Steven Watanabe

AMDG John Maddock wrote:

In "Uniform Random Number Generator" it says that the range can be fixed only after the object is constructed, what values do max_value and min_value have in that case?

If the min and max values are not known at compile time, then min_value and max_value should not be defined and has_fixed_range should be false. (This is somewhat clunky and I don't think anything in the library uses min_value and max_value. Since the standard doesn't have these members, I'd like to deprecate them.)

In "Quasi-Random Number Generators" the text "[Does anyone have a model?] " probably needs replacing with something?

Yep. I don't know that it's worth mentioning Quasi-Random Number Generators at all, since the library doesn't provide any.

In Table 1.5 what does the relative speed indicate? Is smaller better? Or...?

Larger is better. It's stated above the table. It appears to be scaled so that mt19937 is 100. I'll change the entries to match the Performance section, which has the heading "relative speed compared to fastest [percent]." Is that clearer?

Table 1.6 could use updating with more modern machines/compilers.

I'm working on generating quickbook automatically from the output of random_speed.cpp.

Table 1.7 has some entries with just a "?", you might find some help in describing these distributions from http://www.boost.org/doc/libs/1_41_0/libs/math/doc/sf_and_dist/html/math_too..., or then again you may not ;-)

Thanks. I'll take a look.

In "Header <boost/random/additive_combine.hpp>" the synopsis flows off the page, some of the others are probably too wide as well. I find generating a PDF and then checking all the "No space for an element, trying to recover" messages a good way to track these down. Might need some changes to the code formatting to make these readable if they're Doxygen generated? Let me know if you need help in PDF generation.

Fixing this will probably require changes to the BoostBook stylesheets. The original code is split onto multiple lines.

Performance section could probably use more up to date numbers.

I've only skimmed the reference section, but I did notice that the lagged_fibanacci types lacked references.

Yep. I've been slowly tracking down missing references. In Christ, Steven Watanabe

AMDG John Maddock wrote:

...

...

In "Header <boost/random/additive_combine.hpp>" the synopsis flows off the page, some of the others are probably too wide as well.

Fixing this will probably require changes to the BoostBook stylesheets. The original code is split onto multiple lines.

Oh :-(

I suspect this is Doxygen messing things up then, because there's nothing in quickbook/boostbook/docbook that will change code formatting like this that I know of.

Yep. It's doxygen all right. I don't see any good way to fix it. In Christ, Steven Watanabe

2009/11/26 Paul A. Bristow <pbristow@hetp.u-net.com>:

PPS I've also started on a Template/Prototype to guide people doing their docs using the QuickBook/Doxygen/Index/hetp/pdf toolchain but development has stalled.  I'll try to get back to it.

That would be really helpful. We should discuss this on the documentation list. Daniel