altitude validity

[Greg Troxel]

(I'm helping someone with a Free Software program that uses libgps, but
my question stands on its own.)

in gps.h, I see

  #define ALTITUDE_SET    (1llu<<5)

and earlier

    double altitude;    // DEPRECATED, undefined.                               
                                                                                
                                      
    double altHAE;      /* Altitude, height above ellipsoid.                    
                                                                                
                                      
                         * in meters and probably WGS84                         
                                                                                
                                      
                         * (valid if mode == 3)                                 
                                                                                
                                      
                         * MSL = altHAE - geoid_sep */
    double altMSL;      /* Altitude MSL (maybe EGM2008) */


So some things I don't quite understand:

1) It looks like altitude is there still but it will be uninitialized.
This means people with code that doesn't cope will be able to compile
but then hit Undefined Behavior. 

2) altHAE is set to be valid in mode 3, and there is no comment about
altMSL.   And, presumably both are valid if ALTITUDE_SET is on, and if
not on, neither are.

2A) This means therefore that if a receiver provides one of altHAE or
altMSL, but not the other, gpsd will use its own geoid model to compute
the other, and thus the user gets both or none.

3) Someone who wants normal-people-altitude, sort of "WGS84 height above
geoid" or (NA only) "NAVD88, ish" would want to say
    if API >= 9
       read altMSL
    else
      read altitude
    endif



Did I get that all of this right?