Skip Menu |

This queue is for tickets about the Geo-KML CPAN distribution.

Report information
The Basics
Id: 74041
Status: rejected
Priority: 0/
Queue: Geo-KML

People
Owner: Nobody in particular
Requestors: BBYRD [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: Normal
Broken in: 0.92
Fixed in: (no value)



Subject: Documentation needs better examples
The documentation appears to be very light on examples. Geo::KML provides a few methods to read a KML file, but nothing about adding elements, changing things, etc. I'd like to be able to create a KML file from scratch, but it looks like I need to deep-dive into the code to figure out exactly how to do that.
Subject: Re: [rt.cpan.org #74041] Documentation needs better examples
Date: Mon, 16 Jan 2012 17:52:31 +0100
To: Brendan Byrd via RT <bug-Geo-KML [...] rt.cpan.org>
From: Mark Overmeer <secretaris [...] nluug.nl>
* Brendan Byrd via RT (bug-Geo-KML@rt.cpan.org) [120116 15:44]: Show quoted text
> Mon Jan 16 10:44:14 2012: Request 74041 was acted upon. > Transaction: Ticket created by BBYRD > Queue: Geo-KML > Subject: Documentation needs better examples > Broken in: 0.92 > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74041 > > > > The documentation appears to be very light on examples. Geo::KML > provides a few methods to read a KML file, but nothing about adding > elements, changing things, etc.
It does not provide an abstract for KML objects, but is only able to produce valid KML. Did you look at examples/kml-explain.pl ? Show quoted text
> I'd like to be able to create a KML file from scratch, but it looks like > I need to deep-dive into the code to figure out exactly how to do that.
Life is not always easy ;-) But at least, the result is correct. Feel invited to provide nice examples. -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
On Mon Jan 16 11:52:52 2012, secretaris@nluug.nl wrote: Show quoted text
> * Brendan Byrd via RT (bug-Geo-KML@rt.cpan.org) [120116 15:44]: > > It does not provide an abstract for KML objects, but is only able > to produce valid KML. Did you look at examples/kml-explain.pl ?
No, but I did eventually figure it out that writeKML just needs a HASH data structure, starting with the inside of <kml>. While this is somewhat documented in separate modules (XML::Compile), it wasn't immediately obvious from the SYNOPSIS (which is, IMHO, the most important part of the documentation). Show quoted text
> > I'd like to be able to create a KML file from scratch, but it looks like > > I need to deep-dive into the code to figure out exactly how to do that.
> > Life is not always easy ;-) But at least, the result is correct. > Feel invited to provide nice examples.
Gladly. Just as soon as I actually get it to produce valid KML. (See next bug.)
Subject: Re: [rt.cpan.org #74041] Documentation needs better examples
Date: Mon, 16 Jan 2012 23:07:11 +0100
To: Brendan Byrd via RT <bug-Geo-KML [...] rt.cpan.org>
From: Mark Overmeer <secretaris [...] nluug.nl>
* Brendan Byrd via RT (bug-Geo-KML@rt.cpan.org) [120116 18:57]: Show quoted text
> Queue: Geo-KML > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74041 > > > No, but I did eventually figure it out that writeKML just needs a HASH > data structure, starting with the inside of <kml>. While this is > somewhat documented in separate modules (XML::Compile), it wasn't > immediately obvious from the SYNOPSIS (which is, IMHO, the most > important part of the documentation).
The HASH is too complex/large for the SYNOPSIS. But if you read the DESCRIPTION (required reading for this module, because there are some complications), then you see how to work with it. You'll manage, because other people were able to get it to work as well. -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
On Mon Jan 16 17:07:21 2012, secretaris@nluug.nl wrote: Show quoted text
> > The HASH is too complex/large for the SYNOPSIS. But if you read the > DESCRIPTION (required reading for this module, because there are some > complications), then you see how to work with it. You'll manage, > because other people were able to get it to work as well.
I may able to produce a smallish one for the SYNOPSIS, and a larger one for the DESCRIPTION (that still isn't too large). I'll be sure to provide a patch for the Pod as soon as I can get this thing to compile right.
Subject: Re: [rt.cpan.org #74041] Documentation needs better examples
Date: Mon, 16 Jan 2012 23:34:52 +0100
To: Brendan Byrd via RT <bug-Geo-KML [...] rt.cpan.org>
From: Mark Overmeer <mark [...] overmeer.net>
* Brendan Byrd via RT (bug-Geo-KML@rt.cpan.org) [120116 22:29]: Show quoted text
> Queue: Geo-KML > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74041 > > > On Mon Jan 16 17:07:21 2012, secretaris@nluug.nl wrote:
> > > > The HASH is too complex/large for the SYNOPSIS. But if you read the > > DESCRIPTION (required reading for this module, because there are some > > complications), then you see how to work with it. You'll manage, > > because other people were able to get it to work as well.
> > I may able to produce a smallish one for the SYNOPSIS, and a larger one > for the DESCRIPTION (that still isn't too large). I'll be sure to > provide a patch for the Pod as soon as I can get this thing to compile > right.
As long as they are very small... I prefer well worked-out examples in the examples/* directory for such complex things. -- Thanks in advance, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Will do if you can solve this one: xAL. AddressDetails => { AddressType => "Residential", CurrentStatus => "ACTIVE", ValidFromDate => "1 Jan 2000", Country => { #CountryName => XML::LibXML::Element->new('CountryName')->appendText('United States'), CountryNameCode => { Scheme => 'iso.3166-2', _ => 'US' }, CountryName => 'United States', AdministrativeArea => { Type => 'State', AdministrativeAreaName => [ { Type => 'Abbreviation', _ => $row->{ST} }, { Type => 'Official', _ => $st_abbr{$row->{ST}} }, ], SubAdministrativeArea => { Type => 'County', SubAdministrativeAreaName => { Type => 'Official', _ => 'JEFFERSON' }, Locality => { LocalityName => { Type => 'Official', _ => $row->{City} }, Thoroughfare => { cho_ThoroughfareNumber => [ { ThoroughfareNumber => $row->{'St #'} } ], ThoroughfareName => $row->{Street}, } } }, PostalCode => { PostalCodeNumber => $row->{Zip}, }, }, }, PostalServiceElements => { AddressLatitude => { _ => $ll[1] }, AddressLongitude => { _ => $ll[0] }, }, }, This just plain doesn't work in any fashion. Tried just about everything for the past two hours. I get stuff like: <xal:AddressDetails AddressType="Residential" CurrentStatus="ACTIVE" ValidFromDate="1 Jan 2000"> <xal:PostalServiceElements>38.000000-85.779589</xal:PostalServiceElements> <xal:Country>USUnited States<xal:AdministrativeArea Type="State">KY<xal:SubAdministrativeArea Type="County"><xal:Locality><xal:Thoroughfare>1001MAIN AVE</xal:Thoroughfare></xal:Locality></xal:SubAdministrativeArea><xal:PostalCode>40222-5555</xal:PostalCode></xal:AdministrativeArea></xal:Country> </xal:AddressDetails>
Subject: Re: [rt.cpan.org #74041] Documentation needs better examples
Date: Tue, 17 Jan 2012 01:00:01 +0100
To: Brendan Byrd via RT <bug-Geo-KML [...] rt.cpan.org>
From: Mark Overmeer <mark [...] overmeer.net>
* Brendan Byrd via RT (bug-Geo-KML@rt.cpan.org) [120116 23:21]: Show quoted text
> Queue: Geo-KML > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74041 > > > Will do if you can solve this one: xAL. > This just plain doesn't work in any fashion. Tried just about > everything for the past two hours. I get stuff like:
Can you provide a full example (including script) and what you exactly expect? Please send it to mark@overmeer.net. I have no time for it now (go to bed, it's 1am here), but will look at it tomorrow. -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Removed from CPAN