nit: README.md example should use Document(…)

[stapelberg]

Thanks for this useful library!

I noticed that the example from README.md cannot be imported into Google Earth as-is because it nests Placemarks underneath the <kml> tag, whereas it should nest them underneath a <Document> tag.

Other examples are correct in that regard, but it would be good to fix this one, too, I think :)

[twpayne]

Thanks for the feedback!

This example is taken from the first example in the KML tutorial.

From my understanding of the KML specification, a kml containing a single top-level Placemark is allowed:

• kml Elements: "A basic element contains 0 or 1 Feature and 0 or 1 NetworkLinkControl"
• Feature Elements: A Feature can be a Document, Folder, NetworkLink, Placemark, GroundOverlay, PhotoOverlay, or ScreenOverlay.

Does Google Earth emit an error when importing the example?

[stapelberg]

Ah, sorry, I must have modified the example to include multiple placemarks. Just tried to reproduce this, and Google Earth indeed accepts the example file as-is.

So, it would still be good to change it to be more easily extensible, I think, but it’s clearly not a bug — up to you :).

[twpayne]

Thanks for following up :)

The package is designed as a thin wrapper for generating KML documents. "Protection against generating invalid documents" and "concealment of KML complexity" are explicit non-goals. I like the 1:1 mapping between examples in the package and examples in the KML tutorial.

It would be awesome if the library were able to catch more errors at compile time (e.g. if kml.KML(kml.Placemark(), kml.Placemark()) would not compile while kml.KML(kml.Placemark(), kml.NetworkLinkControl()) did compile). However, I'm not sure that this is reasonably possible within the confines of Go's type system (assuming that each element type has a corresponding unique Go type). Given the number of distinct KML element types, any such system would likely need to be automatically generated from the KML specification somehow.

A second option would be to add a function to validate the KML structure. As this could be done at runtime, it would make fewer demands on Go's type system.

I'll open issues for both of the above, but close this issue as "working as intended" for now.