Re: [boost] [review] pqs

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2006-06-07 17:47:50

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>&thinsp;<i>m</i><sup>2</sup>&thinsp;<sup>-2</sup>

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/