[fitswcs] WCS documents

[Eric Greisen]

William Pence writes:
 > Peter Teuben's suggestion, below, to add more examples to the current
 > keyword units proposal highlights the awkwardness of the current situation:
 > the convention for enclosing the keyword units in square brackets is being
 > defined in one place (proposed to be added to section 5.3 of the FITS
 > Standard), but recommendations for the contents of the units string itself
 > are defined in another place (Appendix B of WCS Paper I).   I think these
 > proposals need to be merged into a common proposal that would replace the 2
 > sentences that are currently in the Units section 5.3 in the FITS Standard. 
 > Section 5.3 is the logical place to put all units-related information; other
 > sections of the Standard which need to deal with units (e.g., the discussion
 > of the TUNITSn keyword in sections 8.1.2 and 8.3.2) simply refer back to
 > section 5.3.  I think it is a bit inappropriate to have the discussion of
 > the allowed units strings only in the WCS paper, because this is relevant in
 > many other contexts that have nothing to do with WCS.
 > 
 > So, I propose the following:  We remove appendix B from the WCS paper, merge
 > it with the current keyword units proposal at
 > http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/keywordunits.html, and submit
 > this as a separate proposal to replace the current section 5.3 in the FITS
 > Standard. 
 > 
 > This has a number of advantages:
 > 
 > 1.  It simplifies the WCS paper.  All the WCS paper needs to state is:
 > "Units must follow the prescriptions of section 5.3 of the FITS Standard". 
 > This will also remove any debate about the allowed units strings when the
 > WCS papers come up for a vote.  I believe Appendix B could be removed from
 > Paper I with little or no change to the rest of the paper and thus should
 > not introduce any additional delay in getting the WCS Papers approved.  I
 > may have missed it, but I didn't see any reference to Appendix B in the body
 > of the paper.  
 > 
 > 2.  This new Units proposal can be prepared and submitted to the FITS
 > committees very quickly.  Someone just needs to merge the text from the 2
 > separate proposals, and perhaps make a few editorial changes to make the
 > language suitable for inclusion in the FITS Standard.  Eric is probably the
 > logical person to do this, but I am certainly willing to help.
 > 
 > Does anyone else think this is a good idea??
 > 
 > -Bill
 > 
 > Peter Teuben wrote:
 > > 
 > > Bill,
 > >   do we have a good link to the IAU Style Manual. I don't even think I have
 > > a copy of it, despite that we often talked about it in the NOST document(s).
 > > 
 > > One thing I was wondering about is the academic possibility that there
 > > is a units which requires a lot of characters, so we could run out of space.
 > > 
 > > It would be good to add one or two more example or more complex variables,
 > > e.g. G (gravitational constant) and something with a bit more "math" to
 > > show the syntax.
 > > 
 > > Secondly, what is the requirement if something is dimensionless. Leave it out,
 > > or use [] explicitly? THings that just came to mind as I revisited this page.
 > > 
 > > -peter
 > > 

The discussion above just illustrates why I am opposed to pulling the
units out of WCS.  This will become another Y2K discussion - after 5
years or so in Paper I - which will drag on forever.  If we pull it
from Paper I it will be 10 years before it is adopted.  If we leave it
hidden away, it may be approved.  We can pull it if it causes major
discussion where it is.  Paper I of course reeferences Appendix B in
the section on CUNITns.  The [] nomenclature CANNOT be anything but a
suggestion.  No software can depend on parsing "/ [????]" because
there has been explicitly no grammar specified for comments for 20
years now and so [??] is likely to appear without units in it.  And we
cannot prohibit it in future either.

Thus, the [] is nice but at best only a suggestion.  Worries about the
length of contents - whch will in general not fit in 36 characters
starting at col 41 - is just the beginning.  There is a potential
problem for CUNITns which at least gets to start much sooner on the
header card.

What thing has units that is not in a sense a coordinate?  I put the
example of RESTFRQ in the new draft of Paper I - that is a frequency
but a special one.  Nonetheless it is related to WCS.

If you pull the units appendix, do you also pull defining CUNITns to
some separate paper.  Note the new paper will still have to go to A&A.
This is awfully messy for a minor convenience.

Eric Greisen