--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "XML::RSS 3"
+.TH XML::RSS 3 "2009-10-08" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+XML::RSS \- creates and updates RSS files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 10
+\& # create an RSS 1.0 file (http://purl.org/rss/1.0/)
+\& use XML::RSS;
+\& my $rss = XML::RSS\->new(version => \*(Aq1.0\*(Aq);
+\& $rss\->channel(
+\& title => "freshmeat.net",
+\& link => "http://freshmeat.net",
+\& description => "the one\-stop\-shop for all your Linux software needs",
+\& dc => {
+\& date => \*(Aq2000\-08\-23T07:00+00:00\*(Aq,
+\& subject => "Linux Software",
+\& creator => \*(Aqscoop@freshmeat.net\*(Aq,
+\& publisher => \*(Aqscoop@freshmeat.net\*(Aq,
+\& rights => \*(AqCopyright 1999, Freshmeat.net\*(Aq,
+\& language => \*(Aqen\-us\*(Aq,
+\& },
+\& syn => {
+\& updatePeriod => "hourly",
+\& updateFrequency => "1",
+\& updateBase => "1901\-01\-01T00:00+00:00",
+\& },
+\& taxo => [
+\& \*(Aqhttp://dmoz.org/Computers/Internet\*(Aq,
+\& \*(Aqhttp://dmoz.org/Computers/PC\*(Aq
+\& ]
+\& );
+\&
+\& $rss\->image(
+\& title => "freshmeat.net",
+\& url => "http://freshmeat.net/images/fm.mini.jpg",
+\& link => "http://freshmeat.net",
+\& dc => {
+\& creator => "G. Raphics (graphics at freshmeat.net)",
+\& },
+\& );
+\&
+\& $rss\->add_item(
+\& title => "GTKeyboard 0.85",
+\& link => "http://freshmeat.net/news/1999/06/21/930003829.html",
+\& description => "GTKeyboard is a graphical keyboard that ...",
+\& dc => {
+\& subject => "X11/Utilities",
+\& creator => "David Allen (s2mdalle at titan.vcu.edu)",
+\& },
+\& taxo => [
+\& \*(Aqhttp://dmoz.org/Computers/Internet\*(Aq,
+\& \*(Aqhttp://dmoz.org/Computers/PC\*(Aq
+\& ]
+\& );
+\&
+\& $rss\->textinput(
+\& title => "quick finder",
+\& description => "Use the text input below to search freshmeat",
+\& name => "query",
+\& link => "http://core.freshmeat.net/search.php3",
+\& );
+\&
+\& # Optionally mixing in elements of a non\-standard module/namespace
+\&
+\& $rss\->add_module(prefix=>\*(Aqmy\*(Aq, uri=>\*(Aqhttp://purl.org/my/rss/module/\*(Aq);
+\&
+\& $rss\->add_item(
+\& title => "xIrc 2.4pre2",
+\& link => "http://freshmeat.net/projects/xirc/",
+\& description => "xIrc is an X11\-based IRC client which ...",
+\& my => {
+\& rating => "A+",
+\& category => "X11/IRC",
+\& },
+\& );
+\&
+\& $rss\->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
+\&
+\& # create an RSS 2.0 file
+\& use XML::RSS;
+\& my $rss = XML::RSS\->new (version => \*(Aq2.0\*(Aq);
+\& $rss\->channel(title => \*(Aqfreshmeat.net\*(Aq,
+\& link => \*(Aqhttp://freshmeat.net\*(Aq,
+\& language => \*(Aqen\*(Aq,
+\& description => \*(Aqthe one\-stop\-shop for all your Linux software needs\*(Aq,
+\& rating => \*(Aq(PICS\-1.1 "http://www.classify.org/safesurf/" 1 r (SS~~000 1))\*(Aq,
+\& copyright => \*(AqCopyright 1999, Freshmeat.net\*(Aq,
+\& pubDate => \*(AqThu, 23 Aug 1999 07:00:00 GMT\*(Aq,
+\& lastBuildDate => \*(AqThu, 23 Aug 1999 16:20:26 GMT\*(Aq,
+\& docs => \*(Aqhttp://www.blahblah.org/fm.cdf\*(Aq,
+\& managingEditor => \*(Aqscoop@freshmeat.net\*(Aq,
+\& webMaster => \*(Aqscoop@freshmeat.net\*(Aq
+\& );
+\&
+\& $rss\->image(title => \*(Aqfreshmeat.net\*(Aq,
+\& url => \*(Aqhttp://freshmeat.net/images/fm.mini.jpg\*(Aq,
+\& link => \*(Aqhttp://freshmeat.net\*(Aq,
+\& width => 88,
+\& height => 31,
+\& description => \*(AqThis is the Freshmeat image stupid\*(Aq
+\& );
+\&
+\& $rss\->add_item(title => "GTKeyboard 0.85",
+\& # creates a guid field with permaLink=true
+\& permaLink => "http://freshmeat.net/news/1999/06/21/930003829.html",
+\& # alternately creates a guid field with permaLink=false
+\& # guid => "gtkeyboard\-0.85"
+\& enclosure => { url=>$url, type=>"application/x\-bittorrent" },
+\& description => \*(Aqblah blah\*(Aq
+\&);
+\&
+\& $rss\->textinput(title => "quick finder",
+\& description => "Use the text input below to search freshmeat",
+\& name => "query",
+\& link => "http://core.freshmeat.net/search.php3"
+\& );
+\&
+\& # create an RSS 0.9 file
+\& use XML::RSS;
+\& my $rss = XML::RSS\->new( version => \*(Aq0.9\*(Aq );
+\& $rss\->channel(title => "freshmeat.net",
+\& link => "http://freshmeat.net",
+\& description => "the one\-stop\-shop for all your Linux software needs",
+\& );
+\&
+\& $rss\->image(title => "freshmeat.net",
+\& url => "http://freshmeat.net/images/fm.mini.jpg",
+\& link => "http://freshmeat.net"
+\& );
+\&
+\& $rss\->add_item(title => "GTKeyboard 0.85",
+\& link => "http://freshmeat.net/news/1999/06/21/930003829.html"
+\& );
+\&
+\& $rss\->textinput(title => "quick finder",
+\& description => "Use the text input below to search freshmeat",
+\& name => "query",
+\& link => "http://core.freshmeat.net/search.php3"
+\& );
+\&
+\& # print the RSS as a string
+\& print $rss\->as_string;
+\&
+\& # or save it to a file
+\& $rss\->save("fm.rdf");
+\&
+\& # insert an item into an RSS file and removes the oldest ones if
+\& # there are already 15 items or more
+\& my $rss = XML::RSS\->new;
+\& $rss\->parsefile("fm.rdf");
+\&
+\& while (@{$rss\->{\*(Aqitems\*(Aq}} >= 15)
+\& {
+\& pop(@{$rss\->{\*(Aqitems\*(Aq});
+\& }
+\&
+\& $rss\->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
+\& link => "http://freshmeat.net/news/1999/06/21/930003958.html",
+\& mode => \*(Aqinsert\*(Aq
+\& );
+\&
+\& # parse a string instead of a file
+\& $rss\->parse($string);
+\&
+\& # print the title and link of each RSS item
+\& foreach my $item (@{$rss\->{\*(Aqitems\*(Aq}}) {
+\& print "title: $item\->{\*(Aqtitle\*(Aq}\en";
+\& print "link: $item\->{\*(Aqlink\*(Aq}\en\en";
+\& }
+\&
+\& # output the RSS 0.9 or 0.91 file as RSS 1.0
+\& $rss\->{output} = \*(Aq1.0\*(Aq;
+\& print $rss\->as_string;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This module provides a basic framework for creating and maintaining
+\&\s-1RDF\s0 Site Summary (\s-1RSS\s0) files. This distribution also contains many
+examples that allow you to generate \s-1HTML\s0 from an \s-1RSS\s0, convert between
+0.9, 0.91, and 1.0 version, and other nifty things.
+This might be helpful if you want to include news feeds on your Web
+site from sources like Slashdot and Freshmeat or if you want to syndicate
+your own content.
+.PP
+\&\s-1XML::RSS\s0 currently supports 0.9, 0.91, and 1.0 versions of \s-1RSS\s0.
+See http://backend.userland.com/rss091 for information on \s-1RSS\s0 0.91.
+See http://www.purplepages.ie/RSS/netscape/rss0.90.html for \s-1RSS\s0 0.9.
+See http://web.resource.org/rss/1.0/ for \s-1RSS\s0 1.0.
+.PP
+\&\s-1RSS\s0 was originally developed by Netscape as the format for
+Netscape Netcenter channels, however, many Web sites have since
+adopted it as a simple syndication format. With the advent of \s-1RSS\s0 1.0,
+users are now able to syndication many different kinds of content
+including news headlines, threaded measages, products catalogs, etc.
+.PP
+\&\fBNote:\fR In order to parse and generate dates (such as \f(CW\*(C`pubDate\*(C'\fR
+and \f(CW\*(C`dc:date\*(C'\fR) it is recommended to use DateTime::Format::Mail and
+DateTime::Format::W3CDTF , which is what \s-1XML::RSS\s0 uses internally
+and requires.
+.SH "METHODS"
+.IX Header "METHODS"
+.IP "\s-1XML::RSS\-\s0>new(version=>$version, encoding=>$encoding, output=>$output, stylesheet=>$stylesheet_url, 'xml:base'=>$base)" 4
+.IX Item "XML::RSS->new(version=>$version, encoding=>$encoding, output=>$output, stylesheet=>$stylesheet_url, 'xml:base'=>$base)"
+Constructor for \s-1XML::RSS\s0. It returns a reference to an \s-1XML::RSS\s0 object.
+You may also pass the \s-1RSS\s0 version and the \s-1XML\s0 encoding to use. The default
+\&\fBversion\fR is 1.0. The default \fBencoding\fR is \s-1UTF\-8\s0. You may also specify
+the \fBoutput\fR format regardless of the input version. This comes in handy
+when you want to convert \s-1RSS\s0 between versions. The \s-1XML::RSS\s0 modules
+will convert between any of the formats. If you set <encode_output> \s-1XML::RSS\s0
+will make sure to encode any entities in generated \s-1RSS\s0. This is now on by
+default.
+.Sp
+You can also pass an optional \s-1URL\s0 to an \s-1XSL\s0 stylesheet that can be used to
+output an \f(CW\*(C`<?xsl\-stylesheet ... ?>\*(C'\fR meta-tag in the header that will
+allow some browsers to render the \s-1RSS\s0 file as \s-1HTML\s0.
+.Sp
+You can also set \f(CW\*(C`encode_cb\*(C'\fR to a reference to a subroutine that will
+encode the output in a custom way. This subroutine accepts two parameters:
+a reference to the \f(CW\*(C`XML::RSS::Private::Output::Base\*(C'\fR\-derived object (which
+should normally not concern you) and the text to encode. It should return
+the text to encode. If not set, then the module will encode using its
+custom encoding routine.
+.Sp
+xml:base will set an \f(CW\*(C`xml:base\*(C'\fR property as per
+.Sp
+.Vb 1
+\& http://www.w3.org/TR/xmlbase/
+.Ve
+.Sp
+Note that in order to encode properly, you need to handle \*(L"\s-1CDATA\s0\*(R" sections
+properly. Look at XML::RSS::Private::Output::Base's \f(CW\*(C`_default_encode()\*(C'\fR
+method for how to do it properly.
+.IP "add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)" 4
+.IX Item "add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)"
+Adds an item to the \s-1XML::RSS\s0 object. \fBmode\fR and \fBdescription\fR are optional.
+The default \fBmode\fR
+is append, which adds the item to the end of the list. To insert an item, set the mode
+to \fBinsert\fR.
+.Sp
+The items are stored in the array @{$obj\->{'items'}} where
+\&\fB\f(CB$obj\fB\fR is a reference to an \s-1XML::RSS\s0 object.
+.IP "as_string;" 4
+.IX Item "as_string;"
+Returns a string containing the \s-1RSS\s0 for the \s-1XML::RSS\s0 object. This
+method will also encode special characters along the way.
+.IP "channel (title=>$title, link=>$link, description=>$desc, language=>$language, rating=>$rating, copyright=>$copyright, pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs, managingEditor=>$editor, webMaster=>$webMaster)" 4
+.IX Item "channel (title=>$title, link=>$link, description=>$desc, language=>$language, rating=>$rating, copyright=>$copyright, pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs, managingEditor=>$editor, webMaster=>$webMaster)"
+Channel information is required in \s-1RSS\s0. The \fBtitle\fR cannot
+be more the 40 characters, the \fBlink\fR 500, and the \fBdescription\fR
+500 when outputting \s-1RSS\s0 0.9. \fBtitle\fR, \fBlink\fR, and \fBdescription\fR,
+are required for \s-1RSS\s0 1.0. \fBlanguage\fR is required for \s-1RSS\s0 0.91.
+The other parameters are optional for \s-1RSS\s0 0.91 and 1.0.
+.Sp
+To retreive the values of the channel, pass the name of the value
+(title, link, or description) as the first and only argument
+like so:
+.Sp
+\&\f(CW$title\fR = channel('title');
+.IP "image (title=>$title, url=>$url, link=>$link, width=>$width, height=>$height, description=>$desc)" 4
+.IX Item "image (title=>$title, url=>$url, link=>$link, width=>$width, height=>$height, description=>$desc)"
+Adding an image is not required. \fBurl\fR is the \s-1URL\s0 of the
+image, \fBlink\fR is the \s-1URL\s0 the image is linked to. \fBtitle\fR, \fBurl\fR,
+and \fBlink\fR parameters are required if you are going to
+use an image in your \s-1RSS\s0 file. The remaining image elements are used
+in \s-1RSS\s0 0.91 or optionally imported into \s-1RSS\s0 1.0 via the rss091 namespace.
+.Sp
+The method for retrieving the values for the image is the same as it
+is for \fB\f(BIchannel()\fB\fR.
+.IP "parse ($string, \e%options)" 4
+.IX Item "parse ($string, %options)"
+Parses an \s-1RDF\s0 Site Summary which is passed into \fB\f(BIparse()\fB\fR as the first
+parameter. Returns the instance of the object so one can say
+\&\f(CW\*(C`<$rss\-\*(C'\fRparse($string)\->\fIother_method()\fR>>.
+.Sp
+See the \fIadd_module()\fR method for instructions on automatically adding
+modules as a string is parsed.
+.Sp
+\&\f(CW%options\fR is a list of options that specify how parsing is to be done. The
+available options are:
+.RS 4
+.IP "\(bu" 4
+allow_multiple
+.Sp
+Takes an array ref of names which indicates which elements should
+be allowed to have multiple occurrences. So, for example, to parse
+feeds with multiple enclosures
+.Sp
+.Vb 1
+\& $rss\->parse($xml, { allow_multiple => [\*(Aqenclosure\*(Aq] });
+.Ve
+.IP "\(bu" 4
+hashrefs_instead_of_strings
+.Sp
+If true, then some items (so far "\f(CW\*(C`description\*(C'\fR") will become hash-references
+instead of strings (with a \fBcontent\fR key containing their content , \fBif\fR
+they have \s-1XML\s0 attributes. Without this key, the attributes will be ignored
+and there will only be a string. Thus, specifying this option may break
+compatibility.
+.IP "\(bu" 4
+modules_as_arrays
+.Sp
+This option when true, will parse the modules key-value-pairs as an arrayref of
+\&\f(CW\*(C`{ el => $key_name, value => $value, }\*(C'\fR hash-refs to gracefully
+handle duplicate items (see below). It will not affect the known modules such
+as dc (\*(L"Dublin Core\*(R").
+.RE
+.RS 4
+.RE
+.IP "parsefile ($file, \e%options)" 4
+.IX Item "parsefile ($file, %options)"
+Same as \fB\f(BIparse()\fB\fR except it parses a file rather than a string.
+.Sp
+See the \fIadd_module()\fR method for instructions on automatically adding
+modules as a string is parsed.
+.IP "save ($file)" 4
+.IX Item "save ($file)"
+Saves the \s-1RSS\s0 to a specified file.
+.ie n .IP "skipDays (day => $day)" 4
+.el .IP "skipDays (day => \f(CW$day\fR)" 4
+.IX Item "skipDays (day => $day)"
+Populates the skipDays element with the day \f(CW$day\fR.
+.ie n .IP "skipHours (hour => $hour)" 4
+.el .IP "skipHours (hour => \f(CW$hour\fR)" 4
+.IX Item "skipHours (hour => $hour)"
+Populates the skipHours element, with the hour \f(CW$hour\fR.
+.IP "strict ($boolean)" 4
+.IX Item "strict ($boolean)"
+If it's set to 1, it will adhere to the lengths as specified
+by Netscape Netcenter requirements. It's set to 0 by default.
+Use it if the \s-1RSS\s0 file you're generating is for Netcenter.
+strict will only work for \s-1RSS\s0 0.9 and 0.91. Do not use it for
+\&\s-1RSS\s0 1.0.
+.IP "textinput (title=>$title, description=>$desc, name=>$name, link=>$link);" 4
+.IX Item "textinput (title=>$title, description=>$desc, name=>$name, link=>$link);"
+This \s-1RSS\s0 element is also optional. Using it allows users to submit a Query
+to a program on a Web server via an \s-1HTML\s0 form. \fBname\fR is the \s-1HTML\s0 form name
+and \fBlink\fR is the \s-1URL\s0 to the program. Content is submitted using the \s-1GET\s0
+method.
+.Sp
+Access to the \fBtextinput\fR values is the the same as \fB\f(BIchannel()\fB\fR and
+\&\fB\f(BIimage()\fB\fR.
+.IP "add_module(prefix=>$prefix, uri=>$uri)" 4
+.IX Item "add_module(prefix=>$prefix, uri=>$uri)"
+Adds a module namespace declaration to the \s-1XML::RSS\s0 object, allowing you
+to add modularity outside of the the standard \s-1RSS\s0 1.0 modules. At present,
+the standard modules Dublin Core (dc) and Syndication (syn) are predefined
+for your convenience. The Taxonomy (taxo) module is also internally supported.
+.Sp
+The modules are stored in the hash %{$obj\->{'modules'}} where
+\&\fB\f(CB$obj\fB\fR is a reference to an \s-1XML::RSS\s0 object.
+.Sp
+If you want to automatically add modules that the parser finds in
+namespaces, set the \f(CW$XML::RSS::AUTO_ADD\fR variable to a true value. By
+default the value is false. (N.B. \s-1AUTO_ADD\s0 only updates the
+%{$obj\->{'modules'}} hash. It does not provide the other benefits
+of using add_module.)
+.SS "\s-1RSS\s0 1.0 \s-1MODULES\s0"
+.IX Subsection "RSS 1.0 MODULES"
+XML-Namespace-based modularization affords \s-1RSS\s0 1.0 compartmentalized
+extensibility. The only modules that ship \*(L"in the box\*(R" with \s-1RSS\s0 1.0
+are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
+(http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
+(http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriate
+module's documentation for further information.
+.PP
+Adding items from these modules in \s-1XML::RSS\s0 is as simple as adding other
+attributes such as title, link, and description. The only difference
+is the compartmentalization of their key/value paris in a second-level
+hash.
+.PP
+.Vb 1
+\& $rss\->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
+.Ve
+.PP
+For elements of the Dublin Core module, use the key 'dc'. For elements
+of the Syndication module, 'syn'. For elements of the Taxonomy module,
+\&'taxo'. These are the prefixes used in the \s-1RSS\s0 \s-1XML\s0 document itself.
+They are associated with appropriate URI-based namespaces:
+.PP
+.Vb 3
+\& syn: http://purl.org/rss/1.0/modules/syndication/
+\& dc: http://purl.org/dc/elements/1.1/
+\& taxo: http://purl.org/rss/1.0/modules/taxonomy/
+.Ve
+.PP
+The Dublin Core ('dc') hash keys may be point to an array
+reference, which in turn will specify multiple such keys, and render them
+one after the other. For example:
+.PP
+.Vb 9
+\& $rss\->add_item (
+\& title => $title,
+\& link => $link,
+\& dc => {
+\& subject=> ["Jungle", "Desert", "Swamp"],
+\& creator=>$creator,
+\& date=>$date
+\& },
+\& );
+.Ve
+.PP
+Dublin Core elements may occur in channel, image, item(s), and textinput
+\&\*(-- albeit uncomming to find them under image and textinput. Syndication
+elements are limited to the channel element. Taxonomy elements can occur
+in the channel or item elements.
+.PP
+Access to module elements after parsing an \s-1RSS\s0 1.0 document using
+\&\s-1XML::RSS\s0 is via either the prefix or namespace \s-1URI\s0 for your convenience.
+.PP
+.Vb 1
+\& print $rss\->{items}\->[0]\->{dc}\->{subject};
+\&
+\& or
+\&
+\& print $rss\->{items}\->[0]\->{\*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq}\->{subject};
+.Ve
+.PP
+\&\s-1XML::RSS\s0 also has support for \*(L"non-standard\*(R" \s-1RSS\s0 1.0 modularization at
+the channel, image, item, and textinput levels. Parsing an \s-1RSS\s0 document
+grabs any elements of other namespaces which might appear. \s-1XML::RSS\s0
+also allows the inclusion of arbitrary namespaces and associated elements
+when building \s-1RSS\s0 documents.
+.PP
+For example, to add elements of a made-up \*(L"My\*(R" module, first declare the
+namespace by associating a prefix with a \s-1URI:\s0
+.PP
+.Vb 1
+\& $rss\->add_module(prefix=>\*(Aqmy\*(Aq, uri=>\*(Aqhttp://purl.org/my/rss/module/\*(Aq);
+.Ve
+.PP
+Then proceed as usual:
+.PP
+.Vb 1
+\& $rss\->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
+.Ve
+.PP
+You can also set the value of the module's prefix to an array reference
+of \f(CW\*(C`{ el => , val => }\*(C'\fR hash-references, in which case duplicate
+elements are possible:
+.PP
+.Vb 4
+\& $rss\->add_item(title=>$title, link=>$link, my=> [
+\& {el => "rating", value => $rating1, }
+\& {el => "rating", value => $rating2, },
+\& ]
+.Ve
+.PP
+Non-standard namespaces are not, however, currently accessible via a simple
+prefix; access them via their namespace \s-1URL\s0 like so:
+.PP
+.Vb 1
+\& print $rss\->{items}\->[0]\->{\*(Aqhttp://purl.org/my/rss/module/\*(Aq}\->{rating};
+.Ve
+.PP
+\&\s-1XML::RSS\s0 will continue to provide built-in support for standard \s-1RSS\s0 1.0
+modules as they appear.
+.SH "Non-API Methods"
+.IX Header "Non-API Methods"
+.ie n .SS "$rss\->\fIas_rss_0_9()\fP"
+.el .SS "\f(CW$rss\fP\->\fIas_rss_0_9()\fP"
+.IX Subsection "$rss->as_rss_0_9()"
+\&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
+directly. It is kept as is for backwards compatibility with legacy code. Use
+the following code instead:
+.PP
+.Vb 2
+\& $rss\->{output} = "0.9";
+\& my $text = $rss\->as_string();
+.Ve
+.PP
+This function renders the data in the object as an \s-1RSS\s0 version 0.9 feed,
+and returns the resultant \s-1XML\s0 as text.
+.ie n .SS "$rss\->\fIas_rss_0_9_1()\fP"
+.el .SS "\f(CW$rss\fP\->\fIas_rss_0_9_1()\fP"
+.IX Subsection "$rss->as_rss_0_9_1()"
+\&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
+directly. It is kept as is for backwards compatibility with legacy code. Use
+the following code instead:
+.PP
+.Vb 2
+\& $rss\->{output} = "0.91";
+\& my $text = $rss\->as_string();
+.Ve
+.PP
+This function renders the data in the object as an \s-1RSS\s0 version 0.91 feed,
+and returns the resultant \s-1XML\s0 as text.
+.ie n .SS "$rss\->\fIas_rss_1_0()\fP"
+.el .SS "\f(CW$rss\fP\->\fIas_rss_1_0()\fP"
+.IX Subsection "$rss->as_rss_1_0()"
+\&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
+directly. It is kept as is for backwards compatibility with legacy code. Use
+the following code instead:
+.PP
+.Vb 2
+\& $rss\->{output} = "1.0";
+\& my $text = $rss\->as_string();
+.Ve
+.PP
+This function renders the data in the object as an \s-1RSS\s0 version 1.0 feed,
+and returns the resultant \s-1XML\s0 as text.
+.ie n .SS "$rss\->\fIas_rss_2_0()\fP"
+.el .SS "\f(CW$rss\fP\->\fIas_rss_2_0()\fP"
+.IX Subsection "$rss->as_rss_2_0()"
+\&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
+directly. It is kept as is for backwards compatibility with legacy code. Use
+the following code instead:
+.PP
+.Vb 2
+\& $rss\->{output} = "2.0";
+\& my $text = $rss\->as_string();
+.Ve
+.PP
+This function renders the data in the object as an \s-1RSS\s0 version 2.0 feed,
+and returns the resultant \s-1XML\s0 as text.
+.ie n .SS "$rss\->\fIhandle_char()\fP"
+.el .SS "\f(CW$rss\fP\->\fIhandle_char()\fP"
+.IX Subsection "$rss->handle_char()"
+Needed for XML::Parser. Don't use this directly.
+.ie n .SS "$rss\->\fIhandle_dec()\fP"
+.el .SS "\f(CW$rss\fP\->\fIhandle_dec()\fP"
+.IX Subsection "$rss->handle_dec()"
+Needed for XML::Parser. Don't use this directly.
+.ie n .SS "$rss\->\fIhandle_start()\fP"
+.el .SS "\f(CW$rss\fP\->\fIhandle_start()\fP"
+.IX Subsection "$rss->handle_start()"
+Needed for XML::Parser. Don't use this directly.
+.SH "BUGS"
+.IX Header "BUGS"
+Please use rt.cpan.org for tracking bugs. The list of current open
+bugs is at
+ <http://rt.cpan.org/Dist/Display.html?Queue=XML\-RSS>.
+.PP
+To report a new bug, go to
+ <http://rt.cpan.org/Ticket/Create.html?Queue=XML\-RSS>
+.PP
+Please include a failing test in your bug report. I'd much rather
+have a well written test with the bug report than a patch.
+.PP
+When you create diffs (for tests or patches), please use the \f(CW\*(C`\-u\*(C'\fR
+parameter to diff.
+.SH "SOURCE AVAILABILITY"
+.IX Header "SOURCE AVAILABILITY"
+The source is available from the perl.org Subversion server:
+.PP
+<http://svn.perl.org/modules/XML\-RSS/>
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Original code: Jonathan Eisenzopf <eisen@pobox.com>
+.PP
+Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
+<ask@develooper.com>
+.PP
+Currently: Shlomi Fish <shlomif@cpan.org>
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael
+Dornfest <rael@oreilly.com>, Copyright (C) 2006\-2007 Ask Bjoern Hansen
+<ask@develooper.com>.
+.SH "LICENSE"
+.IX Header "LICENSE"
+\&\s-1XML::RSS\s0 is free software. You can redistribute it and/or
+modify it under the same terms as Perl itself.
+.SH "CREDITS"
+.IX Header "CREDITS"
+.Vb 12
+\& Wojciech Zwiefka <wojtekz@cnt.pl>
+\& Chris Nandor <pudge@pobox.com>
+\& Jim Hebert <jim@cosource.com>
+\& Randal Schwartz <merlyn@stonehenge.com>
+\& rjp@browser.org
+\& Kellan Elliott\-McCrea <kellan@protest.net>
+\& Rafe Colburn <rafe@rafe.us>
+\& Adam Trickett <atrickett@cpan.org>
+\& Aaron Straup Cope <asc@vineyard.net>
+\& Ian Davis <iand@internetalchemy.org>
+\& rayg@varchars.com
+\& Shlomi Fish <shlomif@iglu.org.il>
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIperl\fR\|(1), \fIXML::Parser\fR\|(3).
projects / catagits/Gitalist.git / blobdiff