[iaufwg] Final FITS review comments

[William Pence]

Dear IAU FWG members,

Thank you to those of you who submitted comments or suggestions during
the final round of review of the proposed new FITS Standard document.
We now need to reach a consensus on how to deal with each of these
suggestions before voting on whether to accept this document as the new
FITS Standard.

In total, I counted 16 specific suggestions for changes to the document.
Each of these suggestions is listed below, along with a brief proposal
on how to respond to each issue.  I apologize in advance for the brevity
of some of the proposed solutions; these are only suggestions, so if you
disagree with any of proposed responses or can think of a better way to
resolve the issue, please reply with your alternative suggestion.  We
can then discuss the issue further with the goal of reaching a consensus
that the whole group can accept.

If I have overlooked any other issues that need to be resolved before we
can formally vote on accepting this draft as the new FITS Standard,
please let me know.

regards,
Bill


List of remaining open issues regarding the FITS Standard document
------------------------------------------------------------------

1.  from Arnold Rots (23 November 2007)
>It struck me while reading through the comments that it might have
>been useful to add ISO-8601 datetime to the recognized data types.

Response: Adding a new intrinsic data type to FITS, on a par with
Character Strings, Integers, or Floating Point numbers, goes beyond the
current scope of clarifying the FITS standard and cannot be considered
at this time.  It may be more appropriate to consider this as part of
the draft WCS paper on time coordinates.

2. from Andreas Wicenec (17 March):
>The last two sentences in section 3.1 should be dropped, since they
>are not quite correct and don't add any further information to the 
>standard. If anything then one may state that 'limitations due to 
>hardware or software may restrict the  actual size of FITS files'.

For reference, here are the 2 sentences:

   "Software packages that read or write data according to this
   standard could be limited, however, in the size of
   files that are supported. In particular, some software systems
   have historically only supported files up to 2^{31} bytes in
   size (approximately 2.1 GB).

Response: These 2 sentences provide additional information that may be
useful to some readers, and it does no harm to leave them in the
document, even though they are not strictly required to define the FITS
format.

3. from Andreas Wicenec (17 March):
>Section 4.1.1, last sentence: Why not turn this around and say
>instead that Appendix A is the standard syntax description and the
>text is the aid to explain it in natural language?

Response: Appendix A was produced by the previous technical panel (by
Allen Farris) as an unofficial aid for users.  The appendix has never
been certified to be 100% correct.  If there happens to be any
discrepancies or ambiguities between this formal syntax and the text in
the standard, the text in the the standard (now in section 4) takes
precedence.  Also, this syntax is rather complicated, and it is not
uncommon for it to be interpreted incorrectly.

4. from Andreas Wicenec (17 March):
>Section 3.3.1: change to "The last header block must contain the
>END keyword *record* (defined in 4.4.1.1)"
>... and that brings me to the more generic points:
> the usage of 'keyword' and 'keyword record' is kind of synonym in
> the document and I think that this should not be the case. It is
> clearly defined in section 4.1.1 that a
>"keyword record shall consist of a keyword name, a value indicator
> .....". This definition should be used throughout the document
> (including the Appendix A, see below). Thus I would at least
>suggest to define 'Keyword' to be synonym to 'Keyword record' in
>section 2.2, however  I would prefer that what is called 'keyword'
>now to be called 'keyword record'.

Response:  It is common practice to use the term "keyword" as a short
hand for "keyword record";  this should not cause any confusion.  There
are about 452 instances of the word "keyword" in the document; to
require that we use the term "keyword record" instead of just "keyword"
in every instance (although it already is in many cases) would only make
the text more stilted and ponderous without adding any real value.

5. from Andreas Wicenec (17 March):
>I would suggest to change the structure of chapter 4 to follow the
>logic of the document to go from higher level structures to more
>details:
>   Thus I would suggest to change the the TOC to something  like:
>     4 Headers
>         4.1 Keyword Records
>           4.1.1 Syntax
>           4.1.2 Keyword Name
>	  4.1.3 Value
>               4.1.3.1 Character String Type
>               .......
>           4.1.4 Comment
>         4.2 Mandatory and Reserved Keyword Records
> <snip>

Response:  It is debatable whether this reorganization would be of
benefit to readers.  At this late stage in the document review process
it would be unwise to make any last minute changes to the document that
might have unintended consequences, unless really required.

6. from Andreas Wicenec (17 March):
>Since units are not really well supported in FITS keyword
>records  ;-)  I would suggest to move the current section 4.3 out and
>put it into a separate main section. Since it is in fact also
>describing units for the data sections (where it is much more rigidly
>defined) this seems to be more logical and would make section 4 more
>concise.

Response:  It is debatable whether this reorganization would be of
benefit to readers.  At this late stage in the document review process
it would be unwise to make any last minute changes to the document that
might have unintended consequences, unless really required.

7. from Andreas Wicenec (17 March):
>Current section 4.4 is describing "Mandatory and Reserved Keyword
>Records" and I think it should be called like this.

Response:  This change would not be correct because Section 4.4 also
covers additional user-defined keywords.  Since it is difficult to
describe all of these different cases in a short section title, it is
better to just leave the title as "Keywords".

8. from Andreas Wicenec (17 March):
>Appendix A calls a keyword name a keyword_field, could it not be
>keyword_name instead?

Response:  It is called 'field' instead of 'name' because some
keywords do not have a name.

9. from Andreas Wicenec (17 March):
>Appendix A does not define the END keyword record...

Response:  The END keyword is a member of the FITS commentary keyword
record class, therefore there is no need to define it separately.

10. from Ray Norris (17 March)
>In "Defined Terms", do you really mean to use a value-laden statement:
>"Deprecated : To express disapproval of." If you deprecate an obsolete
>practice, you are not necessarily saying that this was a bad choice by
>its originators, but merely that it's no longer appropriate. So perhaps
>a definition such as "Deprecate : To discourage usage of" may be more
>appropriate.

Response:  The intent of this proposed change to the definition of
"Deprecated" is to convey a stronger statement this it is indeed bad
form to use a deprecated feature in newly created FITS files. "To
express disapproval of" is simply the common dictionary definition of
deprecate.  This is not intended to say anything about the originators
of the deprecated FITS feature.

11. from Ray Norris (17 March)
>Table 8.5, I think there should be a footnote defining "radio
>velocity" and "optical velocity", as they do not have a physical basis
>(but are a computational convenience) and so may not be obvious to a
>scientist in 100 years time.

Response:  The following footnote should be added to table 8.5:
- By convention, the "radio" velocity is given by $c(\nu_0 - \nu)/\nu_0$
and the "optical" velocity is given by $c(\lambda_0 - \lambda)/\lambda_0$

12. from Preben Grosbol (1 April):
>in 4.1.2.3, it is mentions that 'All other keywords that have a value
>      should not appear more than once.'
>
>   I accept that one cannot avoid duplicate keywords in headers as
>   such cases already exist.  The value is obviously 'indeterminate'
>   as stated.  Since the case of duplicate keywords are mentions,
>   it may be appropriate to warn against repeating the same keyword
>   with different value types.  I would find it very bad practice to do
>   so and would not expect to find such usage in any existing FITS
>   file.

Response:  The current statement in section 4.1.2.3 already covers this
case because the same keyword name should not be appear more than once,
regardless of whether or not the values have the same data type.

13. from Preben Grosbol (1 April):
>in Appendix F I assume 'FOREIGN' should be 'FOREIGN '

Response: Add the trailing space in 'FOREIGN '

14. from Don Wells (2 April):
>in 1.1, "which lead to" should be "which led to".

Response: change "lead" to "led"

15. from Don Wells (2 April):
>in G.1, TABLE & PCOUNT probably should be in tt font, and
>in G.2.1, 'COMPLEX' & NAXIS2 probably should be in tt font

Response:  The fonts do not reproduce correctly in the colored
"differences" document (for obscure technical reasons), but the fonts
are correct in the actual draft standard document.

16.  from Mark Calabretta:
>The new Standard should note any inconsistencies in syntax
>between previous versions of the Standard, either as an
>appendix or as footnotes throughout the document.

I am unsure how to respond to this suggestion.  No one seems to know of
any specific cases of changed syntax that should be documented, and no
one has volunteered to take on the task of searching through the
documents to look for any such cases. I can't gauge how the FWG as a
whole feels about this issue because there has been so little discussion
so far.  A couple people (Allen and Shaw) have seemed to question
whether the Standard is in fact the best place for this type of
information.  Perhaps it would be more appropriate to put this in a
separate FITS Implementor's Guide along with other practical guidelines.

I would like to hear how other members feel about this issue.  Is this
issue important enough that it must be addressed immediately?  What
is the scope of changes that should be documented, i.e., would we only
include any changes that have occurred between versions 1.0 of the
Standard and the current draft version 3.0, or are we also talking about
any changes with respect to the original FITS Papers?  Is anyone willing
to take on this task of making a detailed comparison of the different
versions to look for changes?  Personally, I would have to say I don't
really see the urgency in addressing this issue to cause a delay in
voting on the new standard. But I would like to hear what others think.

Bill
-- 
____________________________________________________________________
Dr. William Pence                       William.Pence at nasa.gov
NASA/GSFC Code 662       HEASARC        +1-301-286-4599 (voice)
Greenbelt MD 20771                      +1-301-286-1684 (fax)