[fitsbits] start of Public Comment Period on CONTINUE Long Kwd convention

[Erik Bray]

Hi--some notes inline below:

On 06/24/2015 02:29 AM, van Nieuwenhoven, Richard wrote:
> One of the issues we have struggled with in the last months is the
> longstring behaviour together with the possibilities of long comments.
>
> Our users where wondering why so much of the comments is thrown away
> depending of the length of the string. When a string almost fills up the
> space the comment is "gone" (with longstrings enabled it happens every
> time all the cards are "filled" with data.
>
> Now we found a "hack" in the specification to allow keeping longer
> comments by splitting the string over multiple lines even is there would
> be enough space for the string in less cards. then spread over multiple
> lines there is enough space also for longer comments.
>
> In the current specification I did not wanted to go to extreme
> situations by using string continues like this:
>
> STRKEY  = 'This is a very long string keyword&'  / Optional
> CONTINUE  '&' / very very long comments that must be
> CONTINUE  '' / split over a very big amount of lines

This is the same approach PyFITS has used for a number of years:

 >>> c = fits.Card('STRKEY',
...               'This is a ' + 'long ' * 15 + 'value',
...               'This is a very ' + 'long ' * 15 + 'comment')
 >>> print(c)
STRKEY  = 'This is a long long long long long long long long long long long &' 
CONTINUE  'long long long long value&' 
CONTINUE  '&' / This is a very long long long long long long long long long 
CONTINUE  '' / long long long long long long comment

(Although I found that it won't adopt this convention unless CONTINUE was 
already needed for the value, which is a bit odd.  I might change that.)

In any case, that we both hit on the same approach is a good sign.  I feel that 
this should be documented as part of the standard, including explicit rules for 
when to truncate comments (if at all).

> because I can imagine that other implementations would not expect such
> "strange" usage. But if the new specification explicitly includes such
> an usage it would be a great help for the developers.

They may not explicitly "expect" it, but I think it's compatible with the 
convention as documented, although not explicitly stated.

> My next proposal is to rename the long-string feature to a long-value
> standard. Why limit long values to strings? Why not use it for all values?
>
> INTKEY  = 1245678901234&  / Optional
> CONTINUE  567890& / very very long comments that must be
> CONTINUE  / split over a very big amount of lines
>
> That would not only allow for values with an unlimited level of
> precision but also for very long comments. The COMMENT keyword is no
> alternative here because it can not be automatically detected if the
> COMMENT has a relation to the previous card.

I have mixed feelings about that.  If nothing else I would want the standard to 
be very explicit about what to do in case native software support is not 
available for arbitrary precision values.

> The same accounts for the COMMENT keyword. Currently the comment keyword
> states a COMMENT with no possibility to write a comment that expands
> over multiple lines and distinguish (automatically) it from multiple
> separate comments.

At first I was -1 on this--I have generally treated all COMMENT (and your 
proposal would also apply to HISTORY) cards as implicitly following for each 
other.  For example, I would take a set of COMMENT cards that are grouped 
together and combine them into a single newline-separated string.

On the other hand, this too is just a convention.  I think it would be better if 
it were explicit when a single logical COMMENT card represents a single complete 
comment (and likewise for HISTORY entries).  So using CONTINUE cards following a 
COMMENT card is perhaps the most explicit way to achieve this.

Erik