Beth Jacobson wrote:

Andy Little wrote:

...

"David A. Greene" wrote

...

pqs::velocity::m_div_s - m_per_s? I know this is discussed in the documentation but again, typedefs might be nice to have.

The use of 'div' is meant to stand in for 'divided by' as laid down in 'The Guide for the international System of Units' section 7.12.

I find m_per_s much more readable than m_div_s, but as a native English speaker, both 'per' and 'div' make sense to me. Before stating categorically that 'per' is preferable, I'd like like to hear from non-native speakers. They might be comfortable with 'div' but completely confused by 'per'.

Also being a native English speaker, I find 'per' easier (meters per second) as opposed to 'div' (meters divided by seconds), but the div is to represent the '/' in m/s which is divide in mathematics, but in physics is read as per!

...

...

Output: 1 kg.m+2.s-2 - What does this mean? It wasn't clear to me when I first saw it. Why not use ^ or ** for power?

Again if there is a consensus I will add it but I guess I figured that it was redundant. Does it aid comprehensibility? :

1 kg.m^+2.s^-2

If it does I am happy to use it.

For me, the real bar to comprehensibility is the signs on the exponents. When I see kg.m+2.s-2, I read it as kg-dot-m plus 2-dot-s minus 2. If it could it be written like this:

kg.m2_div_s2

it would be much clearer.

I agree. It would be easier if the output were properly typesetted! However, in physics notation the '+' is not needed, and the '.' is there only because the thin space is not being used! It would be nice to be able to control the output: typesetted+formal -- TeX? -- 1 kg.m^2.s^-2 typesetted+formal (alt.) -- 1 kg.m^2/s^2 informal -- 1 kg.m2_div_s2 descriptive (localised?) -- 1 kilogram meters per second descriptive (normalised) -- 1 newton (is that correct?) The output also asumes ascii, but what if I want to output it to HTML: 1 <i>kg</i> <i>m</i>² ^-2 or MathML (the example not being a correct form, more illustrative): <mval>1</mval> <mtype>m</mtype>...

I disagree. First, David's criticism ("It seems to assume a deep understanding of SI standards and terminology") doesn't apply only to the glossary. You can't get through the first paragraph of "Basic Useage", (shouldn't that be "Usage"?) without encountering "t1_quantity specification", "concrete_quantities", and "named_quantity". These terms are going to send a lot of people straight to the definitions page wherever it's located. Those concepts may be necessary for a complete understanding of pqs, but I suspect that someone could use the library in a simple implementation without knowing much about them.

Exactly. I see two users: those who are just interested in the higher level (group A) and those interested in extending it (group B). It would make sense for the documentation to start with group A, then add more detail and more information, progressing the user to group B. Thus, at the start the user would be happy learning how to do: unit::m distance( 10 ); unit::s time( 5 ); std::cout << "speed = " << ( distance / time ) << std::cout; Then users would be interested in derived units (speed, acceleration, force, ...). This could then lead on to sub-units (millimeters, etc.). Then you could move on to non-SI units. It might be useful to have an SI unit subsection where you give an overview of the library usage, list the unit names in the library (e.g. pqs::unit::m) and which SI unit (name and abbreviation), so that the casual reader can grasp this. You would then move on to things like how to create your own units -- showing how some of the others are created; the constants that are available, then how to derive them. If you take a look at good examples of documentation (e.g. Spirit), they introduce the library at a high level, go into a "how to use the library" section, then a "how to build on and extend the library" section, then (for the curious) an "inner workings" section. The last is optional and not really necessary. The key thing is to know your target audience and then write the documentation for that. I haven't had the opportunity to look into the library for the review, but agree with people that this is something that is needed in Boost and would (if/when standardised) give C++ an extra edge over Java. - Reece _________________________________________________________________ Express yourself instantly with MSN Messenger! Download today it's FREE! http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/