sailing309 / kml-samples

Automatically exported from code.google.com/p/kml-samples
0 stars 0 forks source link

Snippet is deprecated in OGC KML spec but Google documents using deprecated Snippet vs snippet #356

Open GoogleCodeExporter opened 8 years ago

GoogleCodeExporter commented 8 years ago
Google Earth documentation and samples inconsistent with OGC KML 2.2 spec.

Which products are affected?
 KML Standard + KML samples + KML Reference docs

The KML spec clearly shows "Snippet" form deprecated and "snippet" as the 
approved form to use:

  <complexType name="AbstractFeatureType" abstract="true">
    ...
          <choice>
            <annotation>
              <documentation>Snippet deprecated in 2.2</documentation>
            </annotation>
            <element ref="kml:Snippet" minOccurs="0"/>
            <element ref="kml:snippet" minOccurs="0"/>
          </choice>
  </complexType>

http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd

As does the KML spec reference document OGC 07-147r2.

However, the Google Earth documentation only shows the deprecated "Snippet" 
form of kml:SnippetType:

http://code.google.com/apis/kml/documentation/kmlreference.html#snippet

The examples also show the deprecated element as well:

 <Snippet maxLines="4">
    The snippet is a way of
    providing an alternative
    description that will be
    shown in the List view.
  </Snippet> 

Likewise, Google Earth KML samples also use the deprecated form:
http://kml-samples.googlecode.com/svn/trunk/kml/FeatureType/life-of-a-feature-vi
ew-data.kml
http://kml-samples.googlecode.com/svn/trunk/kml/PhotoOverlay/ImagePyramid/space-
needle.kml
etc.

Original issue reported on code.google.com by gjmath...@gmail.com on 26 Jul 2010 at 4:03

GoogleCodeExporter commented 8 years ago
[deleted comment]
GoogleCodeExporter commented 8 years ago
Can this issue have its type changed from Defect to 'Documentation Error' so 
the appropriate person can address it? Thanks.

If OGC KML schema is correct then the Google reference and samples should 
reflect the standard otherwise the google docs should state that the OGC KML 
standard is in error. In either case there should not be a contradiction.

There should be an errata to any erroneous or misleading info in the OGC KML 
spec. If there is one where is it??

Original comment by gjmath...@gmail.com on 4 Feb 2011 at 3:19

GoogleCodeExporter commented 8 years ago
[deleted comment]
GoogleCodeExporter commented 8 years ago
Over year later and documentation still shows the deprecated form of Snippet.
http://code.google.com/apis/kml/documentation/kmlreference.html#snippet

More serious is if the correct form of "snippet" is in KML file and $[Snippet] 
is used in BalloonStyle text then the snippet text is not substituted in the 
displayed balloon. If Snippet or snippet can appear as elements in the KML 
feature that the BalloonStyle mapping should be case-insensitive at least for 
snippet.

This has been documented in the KML Reference Addendum
http://kml4earth.appspot.com/kmlErrata.html#snippet

Original comment by gjmath...@gmail.com on 25 Feb 2012 at 1:27