[QUANTITY] doc consistency

[Pierre Didelon]

Hi Jonathan,
thanks for the infos,
and let's start!

Jonathan McDowell wrote:

> Pierre,
>  I'm sorry, the doc numbering problem is my fault. 
> We originally had the doc as 0.5 and the day we were putting
> it out there was a discussion about IVOA version numbering
> which led me to rename it as 0.2 on the IVOA site, but I forgot
> to renumber it on my own site.
>  The document you have is, within a few minor improvements of
> language, the same one as version 0.21 on my own site
>  http://hea-www.harvard.edu/~jcm/vo/docs

taking v0.21 as ref.
> 
>  Let's concentrate on trying to get this document self-consistent
> now. I'm not so concerned with the XMLSpy stuff at this point,

Ok, step by step is better (at least for a "child-minded" like me).
> but we need to make sure that in the Q doc the UML, the English description
> and the XML serialization are all consistent with each other.

I will try to begin with BasicQuantity, but some remarks may apply to whateverQ.
As for example the fact that during the discussion on the list it appears
(at least to me, I perhaps did not read the doc carefully enough) that some
attributes and/or child tags can be optional while others are mandatory/required.
See the last mail of brian for some precisions http://www.ivoa.net/forum/dm/0520.htm,
I think these kind of informations must be include (clearly) in the document.
concerning BasicQuantity
           Basic Quantity [id attribute optional]
                   UCD - Optional
                   CoordSystem - Optional
                   Units - Required (But if absent in serialization it defaults to "unitless")
                   DataType - Required (But ... it defaults to "string of arbitrary length")
                   Value - Required
                   Accuracy - Optional
it has the advantage that Accuracy can be used or not by diff. group of people,
allowing a kind of agreement on a general behavior.
Then the interface methods which are allowed to return null must be distinguised,
and perhaps the ones which return default ones.

Another point concerning all the levels is related to serialisation. As you
outlined it, it is  a very important point and I feel that a corresponding
method would preferably included in the interface definition at each level.

Tackle now BasicQuantity (BQ), I take fig.1 as the reference exception
for accuracy, which I considered optionnaly present in BQ :

- p.10 §5 It does not support ... coordinate system...
	? method exist few lines below, diag say the reverse...

- p.16
	? BQ is not mentionned here. I know that a complete § is devoted to it (§5),
but some remining and/or additional info concerning it would be nicely included here
as § 6.2.3?

- p.16 §6.2.3 getValue is part of BQ interface? same remark for CQ interface diag of p.14
	ok this concern CQ... but not only ;-)

- p.25 §7.6.1 is this § concerning BQ? Then I would expect usage of basicQuantity tag!
or at least trivialQuantity but not quantity. Form where did this tag emerge?
If it is BQ, >altValues/> is not authorised in ex 2, as it is only relevant
for StandardQantity.


Is this going in the good direction?
Did you expect something else more...?

> As a second step we need to split the English description into a
> pure English-for-astronomers bit and a computer-science-class-description
> bit.
>  Finally we need to list the pieces that are controversial even within
> the Q paradigm: should BasicQ have errors, should it be called AtomicQ, etc.
> 

let's try to pursue the effort,
sincerely yours

-- 
Pierre 
--------------------------------------------------------------------------
DIDELON :@: pdidelon_at_cea.fr        Phone : 33 (0)1 69 08 58 89
CEA SACLAY - Service d'Astrophysique  91191 Gif-Sur-Yvette Cedex
--------------------------------------------------------------------------