some cleanup and example

.gitignore

@@ -0,0 +1,7 @@
+Build
+MANIFEST.bak
+MYMETA.json
+MYMETA.yml
+_build/
+blib/
+*.swp

MANIFEST

@@ -1,13 +1,18 @@
 Build.PL
+Makefile.PL
 Changes
+eg/check_feed.pl
+lib/XML/Feed.pm
 lib/XML/Feed/Content.pm
 lib/XML/Feed/Enclosure.pm
 lib/XML/Feed/Entry.pm
+lib/XML/Feed/Entry/Format/Atom.pm
+lib/XML/Feed/Entry/Format/RSS.pm
 lib/XML/Feed/Format/Atom.pm
 lib/XML/Feed/Format/RSS.pm
-lib/XML/Feed.pm
-MANIFEST.SKIP
 MANIFEST			This list of files
+MANIFEST.SKIP
+META.json
 META.yml
 README
 t/00-compile.t
@@ -24,8 +29,8 @@ t/10-mix-and-match.t
 t/11-xml-base-atom.t
 t/11-xml-base-rss.t
 t/12-multi-categories-atom.t
-t/12-multi-categories.base
 t/12-multi-categories-rss.t
+t/12-multi-categories.base
 t/12-multi-subjects-rss.t
 t/13-category-hash-bug.t
 t/14-enclosures.t
@@ -35,6 +40,10 @@ t/16-convert-mult-categories.t
 t/17-double.t
 t/18-double2.t
 t/19-double3.t
+t/20-no-enclosures.t
+t/21-rss2-permalinks.t
+t/22-bug73160.t
+t/23-eval.t
 t/pod-coverage.t
 t/pod.t
 t/samples/atom-10-example.xml
@@ -46,6 +55,9 @@ t/samples/atom.xml
 t/samples/base_atom.xml
 t/samples/base_rss.xml
 t/samples/category-bug.xml
+t/samples/rss-multiple-categories.xml
+t/samples/rss-multiple-subjects.xml
+t/samples/rss10-datespaces.xml
 t/samples/rss10-double.xml
 t/samples/rss10-double2.xml
 t/samples/rss10-invalid-date.xml
@@ -55,15 +67,5 @@ t/samples/rss20-double.xml
 t/samples/rss20-enclosure.xml
 t/samples/rss20-multi-enclosure.xml
 t/samples/rss20-no-summary.xml
-t/samples/rss20.xml
-t/samples/rss-multiple-categories.xml
-t/samples/rss-multiple-subjects.xml
-Makefile.PL
-META.json
-t/19-double3.t
-t/samples/rss10-double2.xml
-t/20-no-enclosures.t
-t/21-rss2-permalinks.t
 t/samples/rss20-p.xml
-t/22-bug73160.t
-t/samples/rss10-datespaces.xml
+t/samples/rss20.xml

MANIFEST.SKIP

@@ -3,8 +3,8 @@
 \.git
 \.bak$
 _build
-Build
+Build$
 blib
-Makefile
+Makefile$
 ^MYMETA.yml$
 ^MYMETA\.json$

eg/check_feed.pl

@@ -0,0 +1,57 @@
+use strict;
+use warnings;
+use v5.10;
+
+=head1 DESCRIPTION
+
+Given a URL of an Atom or RSS feed or a filename of an already downloaded
+feed, this script will try to parse it and print out what it understands
+from the feed.
+
+=cut
+
+use XML::Feed;
+
+my $src = shift;
+
+die "Usage: $0 FILE|URL\n" if not $src;
+
+my $source = $src;
+if ($src =~ m{^https?://}) {
+	$source = URI->new($src);
+} else {
+	if (not -f $source) {
+		die "'$source' does not look like a URL and it does not exist on the file-system either.\n";
+	}
+}
+
+my $feed = XML::Feed->parse( $source ) or die XML::Feed->errstr;
+say 'Title:     ' . ($feed->title     // '');
+say 'Tagline:   ' . ($feed->tagline   // '');
+say 'Format:    ' . ($feed->format    // '');
+say 'Author:    ' . ($feed->author    // '');
+say 'Link:      ' . ($feed->link      // '');
+say 'Base:      ' . ($feed->base      // '');
+say 'Language:  ' . ($feed->language  // '');
+say 'Copyright: ' . ($feed->copyright // '');
+say 'Modified:  ' . ($feed->modified  // ''); # DateTime object
+say 'Generator: ' . ($feed->generator // '');
+
+for my $entry ($feed->entries) {
+	say '';
+	say '    Link:      ' . ($entry->link          // '');
+	say '    Author:    ' . ($entry->author        // '');
+	say '    Title:     ' . ($entry->title         // '');
+	say '    Caregory:  ' . ($entry->category      // '');
+	say '    Id:        ' . ($entry->id            // '');
+	say '    Issued:    ' . ($entry->issued        // ''); # DateTime object
+	say '    Modified:  ' . ($entry->modified      // ''); # DateTime object
+	say '    Lat:       ' . ($entry->lat           // '');
+	say '    Long:      ' . ($entry->long          // '');
+	say '    Format:    ' . ($entry->format        // '');
+	say '    Tags:      ' . ($entry->tags          // '');
+	say '    Enclosure: ' . ($entry->enclosure     // '');
+	say '    Summary:   ' . ($entry->summary->body // '');
+	say '    Content:   ' . ($entry->content->body // '');
+}
+

lib/XML/Feed.pm

@@ -213,10 +213,10 @@ the various syndication formats. The different flavors of RSS and Atom
 handle data in different ways: date handling; summaries and content;
 escaping and quoting; etc. This module attempts to remove those differences
 by providing a wrapper around the formats and the classes implementing
-those formats (I<XML::RSS> and I<XML::Atom::Feed>). For example, dates are
+those formats (L<XML::RSS> and L<XML::Atom::Feed>). For example, dates are
 handled differently in each of the above formats. To provide a unified API for
 date handling, I<XML::Feed> converts all date formats transparently into
-I<DateTime> objects, which it then returns to the caller.
+L<DateTime> objects, which it then returns to the caller.
 
 =head1 USAGE
 
@@ -232,7 +232,8 @@ Creates a new empty I<XML::Feed> object using the format I<$format>.
 
 =head2 XML::Feed->parse($stream, $format)
 
-Parses a syndication feed identified by I<$stream>. I<$stream> can be any
+Parses a syndication feed identified by I<$stream> and returns an
+I<XML::Feed> obhect. I<$stream> can be any
 one of the following:
 
 =over 4
@@ -335,15 +336,15 @@ A string.
 =head2 $feed->entries
 
 A list of the entries/items in the feed. Returns an array containing
-I<XML::Feed::Entry> objects.
+L<XML::Feed::Entry> objects.
 
 =head2 $feed->items
 
-A synonym for I<$feed->entries>.
+A synonym (alias) for <$feed-E<gt>entries>.
 
 =head2 $feed->add_entry($entry)
 
-Adds an entry to the feed. I<$entry> should be an I<XML::Feed::Entry>
+Adds an entry to the feed. I<$entry> should be an L<XML::Feed::Entry>
 object in the correct format for the feed.
 
 =head2 $feed->as_xml

lib/XML/Feed/Entry.pm

@@ -79,7 +79,7 @@ XML::Feed::Entry - Entry/item in a syndication feed
 
 =head1 DESCRIPTION
 
-I<XML::Feed::Entry> represents an entry/item in an I<XML::Feed> syndication
+I<XML::Feed::Entry> represents an entry/item in an L<XML::Feed> syndication
 feed.
 
 =head1 USAGE
@@ -109,26 +109,26 @@ instead to an offsite URI referenced in the entry.
 
 =head2 $entry->content([ $content ])
 
-Bn I<XML::Feed::Content> object representing the full entry body, or as
+An L<XML::Feed::Content> object representing the full entry body, or as
 much as is available in the feed.
 
 In RSS feeds, this method will look first for
-I<http://purl.org/rss/1.0/modules/content/#encoded> and
-I<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
+L<http://purl.org/rss/1.0/modules/content/#encoded> and
+L<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
 I<E<lt>descriptionE<gt>> element.
 
 =head2 $entry->summary([ $summary ])
 
-An I<XML::Feed::Content> object representing a short summary of the entry.
+An L<XML::Feed::Content> object representing a short summary of the entry.
 Possibly.
 
 Since RSS feeds do not have the idea of a summary separate from the entry
 body, this may not always be what you want. If the entry contains both a
 I<E<lt>descriptionE<gt>> element B<and> another element typically used for
 the full content of the entry--either I<http://www.w3.org/1999/xhtml/body>
-or I<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
+or L<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
 the summary. Otherwise, we assume that there isn't a summary, and return
-an I<XML::Feed::Content> object with an empty string in the I<body>.
+an L<XML::Feed::Content> object with an empty string in the I<body>.
 
 =head2 $entry->category([ $category ])
 
@@ -142,7 +142,7 @@ I<add_category> instead.
 
 =head2 $entry->tags([ $tag ])
 
-A synonym for I<category>;
+A synonym (alias) for I<category>;
 
 =head2 $entry->author([ $author ])