X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FXML%3A%3AAtom%3A%3AFeed.3pm;fp=local-lib5%2Fman%2Fman3%2FXML%3A%3AAtom%3A%3AFeed.3pm;h=aac7e6f52cffcd8ccb8b50e62a1ed000cecd23df;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e

diff --git a/local-lib5/man/man3/XML::Atom::Feed.3pm b/local-lib5/man/man3/XML::Atom::Feed.3pm
new file mode 100644
index 0000000..aac7e6f
--- /dev/null
+++ b/local-lib5/man/man3/XML::Atom::Feed.3pm
@@ -0,0 +1,321 @@
+.\" 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::Atom::Feed 3"
+.TH XML::Atom::Feed 3 "2009-04-24" "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::Atom::Feed \- Atom feed
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 11
+\&    use XML::Atom::Feed;
+\&    use XML::Atom::Entry;
+\&    my $feed = XML::Atom::Feed\->new;
+\&    $feed\->title(\*(AqMy Weblog\*(Aq);
+\&    $feed\->id(\*(Aqtag:example.com,2006:feed\-id\*(Aq);
+\&    my $entry = XML::Atom::Entry\->new;
+\&    $entry\->title(\*(AqFirst Post\*(Aq);
+\&    $entry\->id(\*(Aqtag:example.com,2006:entry\-id\*(Aq);
+\&    $entry\->content(\*(AqPost Body\*(Aq);
+\&    $feed\->add_entry($entry);
+\&    $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
+\&
+\&    my @entries = $feed\->entries;
+\&    my $xml = $feed\->as_xml;
+\&
+\&    ## Get a list of the <link rel="..." /> tags in the feed.
+\&    my $links = $feed\->link;
+\&
+\&    ## Find all of the Atom feeds on a given page, using auto\-discovery.
+\&    my @uris = XML::Atom::Feed\->find_feeds(\*(Aqhttp://www.example.com/\*(Aq);
+\&
+\&    ## Use auto\-discovery to load the first Atom feed on a given page.
+\&    my $feed = XML::Atom::Feed\->new(URI\->new(\*(Aqhttp://www.example.com/\*(Aq));
+.Ve
+.SH "USAGE"
+.IX Header "USAGE"
+.ie n .SS "XML::Atom::Feed\->new([ $stream ])"
+.el .SS "XML::Atom::Feed\->new([ \f(CW$stream\fP ])"
+.IX Subsection "XML::Atom::Feed->new([ $stream ])"
+Creates a new feed object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
+data specified by \fI\f(CI$stream\fI\fR.
+.PP
+Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
+.PP
+Returns the new \fIXML::Atom::Feed\fR object. On failure, returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+\&\fI\f(CI$stream\fI\fR can be any one of the following:
+.IP "\(bu" 4
+Reference to a scalar
+.Sp
+This is treated as the \s-1XML\s0 body of the feed.
+.IP "\(bu" 4
+Scalar
+.Sp
+This is treated as the name of a file containing the feed \s-1XML\s0.
+.IP "\(bu" 4
+Filehandle
+.Sp
+This is treated as an open filehandle from which the feed \s-1XML\s0 can be read.
+.IP "\(bu" 4
+\&\s-1URI\s0 object
+.Sp
+This is treated as a \s-1URI\s0, and the feed \s-1XML\s0 will be retrieved from the \s-1URI\s0.
+.Sp
+If the content type returned from fetching the content at \s-1URI\s0 is
+\&\fItext/html\fR, this method will automatically try to perform auto-discovery
+by looking for a \fI<link>\fR tag describing the feed \s-1URL\s0. If such
+a \s-1URL\s0 is found, the feed \s-1XML\s0 will be automatically retrieved.
+.Sp
+If the \s-1URI\s0 is already of a feed, no auto-discovery is necessary, and the
+feed \s-1XML\s0 will be retrieved and parsed as normal.
+.SS "XML::Atom::Feed\->find_feeds($uri)"
+.IX Subsection "XML::Atom::Feed->find_feeds($uri)"
+Given a \s-1URI\s0 \fI\f(CI$uri\fI\fR, use auto-discovery to find all of the Atom feeds linked
+from that page (using \fI<link>\fR tags).
+.PP
+Returns a list of feed URIs.
+.ie n .SS "$feed\->link"
+.el .SS "\f(CW$feed\fP\->link"
+.IX Subsection "$feed->link"
+If called in scalar context, returns an \fIXML::Atom::Link\fR object
+corresponding to the first \fI<link>\fR tag found in the feed.
+.PP
+If called in list context, returns a list of \fIXML::Atom::Link\fR objects
+corresponding to all of the \fI<link>\fR tags found in the feed.
+.ie n .SS "$feed\->add_link($link)"
+.el .SS "\f(CW$feed\fP\->add_link($link)"
+.IX Subsection "$feed->add_link($link)"
+Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
+the feed as a new \fI<link>\fR tag. For example:
+.PP
+.Vb 5
+\&    my $link = XML::Atom::Link\->new;
+\&    $link\->type(\*(Aqtext/html\*(Aq);
+\&    $link\->rel(\*(Aqalternate\*(Aq);
+\&    $link\->href(\*(Aqhttp://www.example.com/\*(Aq);
+\&    $feed\->add_link($link);
+.Ve
+.ie n .SS "$feed\->add_entry($entry)"
+.el .SS "\f(CW$feed\fP\->add_entry($entry)"
+.IX Subsection "$feed->add_entry($entry)"
+Adds the entry \fI\f(CI$entry\fI\fR, which must be an \fIXML::Atom::Entry\fR object,
+to the feed. If you want to add an entry before existent entries, you can pass optional hash reference containing \f(CW\*(C`mode\*(C'\fR value set to \f(CW\*(C`insert\*(C'\fR.
+.PP
+.Vb 1
+\&  $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
+.Ve
+.ie n .SS "$feed\->entries"
+.el .SS "\f(CW$feed\fP\->entries"
+.IX Subsection "$feed->entries"
+Returns list of XML::Atom::Entry objects contained in the feed.
+.ie n .SS "$feed\->language"
+.el .SS "\f(CW$feed\fP\->language"
+.IX Subsection "$feed->language"
+Returns the language of the feed, from \fIxml:lang\fR.
+.ie n .SS "$feed\->author([ $author ])"
+.el .SS "\f(CW$feed\fP\->author([ \f(CW$author\fP ])"
+.IX Subsection "$feed->author([ $author ])"
+Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
+or \f(CW\*(C`undef\*(C'\fR if there is no author information present.
+.PP
+If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
+representing the author. For example:
+.PP
+.Vb 4
+\&    my $author = XML::Atom::Person\->new;
+\&    $author\->name(\*(AqFoo Bar\*(Aq);
+\&    $author\->email(\*(Aqfoo@bar.com\*(Aq);
+\&    $feed\->author($author);
+.Ve
+.ie n .SS "$feed\->id([ $id ])"
+.el .SS "\f(CW$feed\fP\->id([ \f(CW$id\fP ])"
+.IX Subsection "$feed->id([ $id ])"
+Returns an id for the feed. If \fI\f(CI$id\fI\fR is supplied, set the id. When
+generating the new feed, it is your responsibility to generate unique
+\&\s-1ID\s0 for the feed and set to XML::Atom::Feed object. You can use \fIhttp\fR
+permalink, \fItag\fR \s-1URI\s0 scheme or \fIurn:uuid\fR for handy.
+.SH "UNICODE FLAGS"
+.IX Header "UNICODE FLAGS"
+By default, XML::Atom takes off all the Unicode flag fro mthe feed content. For example,
+.PP
+.Vb 1
+\&  my $title = $feed\->title;
+.Ve
+.PP
+the variable \f(CW$title\fR contains \s-1UTF\-8\s0 bytes without Unicode flag set,
+even if the feed title contains some multibyte chracters.
+.PP
+If you don't like this behaviour and wants to andle everything as
+Unicode characters (rather than \s-1UTF\-8\s0 bytes), set
+\&\f(CW$XML::Atom::ForceUnicode\fR flag to 1.
+.PP
+.Vb 1
+\&  $XML::Atom::ForceUnicode = 1;
+.Ve
+.PP
+then all the data returned from XML::Atom::Feed object and
+XML::Atom::Entry object etc., will have Unicode flag set.
+.PP
+The only exception will be \f(CW\*(C`$entry\->content\->body\*(C'\fR, if content
+type is not text/* (e.g. image/gif). In that case, the content body is
+still binary data, without Unicode flag set.
+.SH "CREATING ATOM 1.0 FEEDS"
+.IX Header "CREATING ATOM 1.0 FEEDS"
+By default, XML::Atom::Feed and other classes (Entry, Link and
+Content) will create entities using Atom 0.3 namespaces. In order to
+create 1.0 feed and entry elements, you can set \fIVersion\fR as a
+parameter, like:
+.PP
+.Vb 2
+\&  $feed = XML::Atom::Feed\->new(Version => 1.0);
+\&  $entry = XML::Atom::Entry\->new(Version => 1.0);
+.Ve
+.PP
+Setting those Version to every element would be sometimes painful. In
+that case, you can override the default version number by setting
+\&\f(CW$XML::Atom::DefaultVersion\fR global variable to \*(L"1.0\*(R".
+.PP
+.Vb 1
+\&  use XML::Atom;
+\&
+\&  $XML::Atom::DefaultVersion = "1.0";
+\&
+\&  my $feed = XML::Atom::Feed\->new;
+\&  $feed\->title("blah");
+\&
+\&  my $entry = XML::Atom::Entry\->new;
+\&  $feed\->add_entry($entry);
+\&
+\&  $feed\->version; # 1.0
+.Ve
+.SH "AUTHOR & COPYRIGHT"
+.IX Header "AUTHOR & COPYRIGHT"
+Please see the \fIXML::Atom\fR manpage for author, copyright, and license
+information.