Add special scripts directory handling to make-dist.
[matthijs/upstream/blosxom-plugins.git] / gavinc / rss20
1 # Blosxom Plugin: rss20
2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
3 # Version: 0.003000
4 # Requires: storydate
5 # Suggests: absolute, storytags, geo
6 # Follows:  storydate
7
8 package rss20;
9
10 use strict;
11
12 use vars qw(
13   $flavour
14   $author_email 
15   $author_name 
16   $webmaster_email 
17   $permalink
18   $trackback_link
19   $copyright
20   $generator
21   $category_list
22   $georss
23 );
24
25 # --- Configuration variables -----
26
27 # What flavour string to you want to use for your feed?
28 $flavour = 'rss';
29 #$flavour = 'rss20';
30
31 # What email address should be used as the default author email?
32 # Recommended format is 'email (name)', but bare emails or mailto emails are ok too
33 $author_email = 'author@example.com (A. U. Thor)';
34
35 # What name should be used as the default author name?
36 # Define this only if you don't want to disclose an email address in $author_email.
37 # It will be ignored if $author_email is set.
38 $author_name = '';
39
40 # What email address should feed errors be reported to?
41 # Recommended format is 'email (name)', but bare emails or mailto emails are ok too
42 $webmaster_email = '';
43 #$webmaster_email = 'webmaster@example.com (Web Master)';
44
45 # What do your story permalinks look like?
46 # This must be single-quoted, to defer evaluation; blosxom namespace applies
47 $permalink = '$url$path/$fn.$default_flavour';
48
49 # What link should be used for trackbacks on a story?
50 # This must be single-quoted, to defer evaluation; blosxom namespace applies
51 $trackback_link = '';
52 # $trackback_link = '$url$path/$fn.writeback';
53 # $trackback_link = '$url$path/$fn.$feedback::trackback_flavour';
54
55 # Copyright statement; leave blank to omit.
56 $copyright = '';
57
58 # Generator that produced this feed
59 $generator = "blosxom $blosxom::version";
60
61 # --------------------------------
62 # __END_CONFIG__
63
64 $webmaster_email ||= $author_email;
65
66 my $channel_indent = 8;
67 my $item_indent = 12;
68
69 # Escape <, >, and & to hex-encoded entities for max compatibility in text elements
70 # See http://www.rssboard.org/rss-profile#data-types-characterdata
71 my %escape_text = (
72   '<' => '&#x3C;',
73   '>' => '&#x3E;',
74   '&' => '&#x26;',
75 );
76 my $escape_text_re = join '|' => keys %escape_text;
77
78 # Escape <, >, and & to standard html-encoded entities for in html elements
79 my %escape_html = (
80   '<' => '&lt;',
81   '>' => '&gt;',
82   '&' => '&amp;',
83 );
84 my $escape_html_re = join '|' => keys %escape_html;
85
86 sub start { 
87   _load_templates();
88 }
89
90 my $do_encode = 0;
91 sub story {
92   my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
93
94   # Ignore flavours other than ours
95   return unless $blosxom::flavour eq $flavour;
96
97   # Don't double-encode if someone else has already done it
98   return unless $do_encode || $blosxom::encode_xml_entities;
99  
100   # Because we're inside a loop, we set $do_encode for runs after the first
101   unless ($do_encode) {
102     $do_encode = 1;
103     $blosxom::encode_xml_entities = 0;
104   }
105
106   # Encode and reset encode_xml_entities flag
107   $$title_ref = _escape_text( $$title_ref );
108   $$body_ref  = _escape_html( $$body_ref );
109
110   $category_list = '';
111   if ($blosxom::plugins{storytags}) {
112     for (@storytags::taglist) {
113       $category_list .= qq(<category>$_</category>\n) . ' ' x $item_indent;
114     }
115   }
116
117   $georss = '';
118   if ($blosxom::plugins{geo} && $geo::latitude && $geo::longitude) {
119     $georss = qq(<georss:point>$geo::latitude $geo::longitude</georss:point>\n) .
120       ' ' x $item_indent;
121   }
122
123   return 1;
124 }
125
126 # --- Private subroutines
127
128 sub _escape_text {
129   my ($text) = @_;
130   $text =~ s/($escape_text_re)/$escape_text{$1}/g;
131   return $text;
132 }
133
134 sub _escape_html {
135   my ($html) = @_;
136   $html =~ s/($escape_html_re)/$escape_html{$1}/g;
137   return $html;
138 }
139
140 sub _load_templates {
141   $blosxom::template{$flavour}{'content_type'} = 'text/xml; charset=$blog_encoding';
142
143   $blosxom::template{$flavour}{'date'} = "\n";
144
145   $blosxom::template{$flavour}{'head'} = <<HEAD;
146 <?xml version="1.0" encoding="$blosxom::blog_encoding"?>
147 <rss version="2.0"
148     xmlns:dc="http://purl.org/dc/elements/1.1/"
149     xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
150 HEAD
151
152   if ($blosxom::plugins{geo}) {
153     $blosxom::template{$flavour}{'head'} .= 
154       qq(    xmlns:georss="http://www.georss.org/georss"\n);
155   }
156
157   $blosxom::template{$flavour}{'head'} .= <<HEAD;
158     xmlns:atom="http://www.w3.org/2005/Atom">
159
160     <channel>
161         <title>$blosxom::blog_title</title>
162         <link>$blosxom::url/</link>
163 HEAD
164
165   if ($blosxom::path_info) {
166     $blosxom::template{$flavour}{'head'} .= 
167      ' ' x $channel_indent .
168      qq(<category>$blosxom::path_info</category>\n);
169   }
170   if ($blosxom::blog_description) {
171     $blosxom::template{$flavour}{'head'} .= 
172      ' ' x $channel_indent .
173       qq(<description>$blosxom::blog_description</description>\n);
174   }
175   if ($rss20::author_email) {
176     $blosxom::template{$flavour}{'head'} .= 
177      ' ' x $channel_indent .
178       qq(<managingEditor>$rss20::author_email</managingEditor>\n);
179   }
180   elsif ($rss20::author_name) {
181     $blosxom::template{$flavour}{'head'} .= 
182      ' ' x $channel_indent .
183       qq(<dc:creator>$rss20::author_name</dc:creator>\n);
184   }
185   if ($rss20::webmaster_email) {
186     $blosxom::template{$flavour}{'head'} .= 
187      ' ' x $channel_indent .
188       qq(<webMaster>$rss20::webmaster_email</webMaster>\n);
189   }
190   if ($rss20::copyright) {
191     $blosxom::template{$flavour}{'head'} .= 
192      ' ' x $channel_indent .
193       qq(<copyright>$rss20::copyright</copyright>\n);
194   }
195   my $path_info_full = $blosxom::path_info_full || "$blosxom::path_info/index.rss";
196   $blosxom::template{$flavour}{'head'} .= <<HEAD;
197         <pubDate>\$storydate::latest_rfc822</pubDate>
198         <language>$blosxom::blog_language</language>
199         <generator>$rss20::generator</generator>
200         <atom:link href="$blosxom::url$path_info_full" rel="self" type="application/rss+xml" />
201         <sy:updatePeriod>hourly</sy:updatePeriod>
202         <sy:updateFrequency>1</sy:updateFrequency>
203         <sy:updateBase>2000-01-01T12:00+00:00</sy:updateBase>
204 HEAD
205
206   $blosxom::template{$flavour}{'story'} = <<STORY;
207
208         <item>
209             <title>\$title</title>
210             <link>$rss20::permalink</link>
211             <guid isPermaLink="true">$rss20::permalink</guid>
212             <pubDate>\$storydate::story_rfc822</pubDate>
213 STORY
214
215   if ($rss20::trackback_link) {
216     $blosxom::template{$flavour}{'story'} .= 
217       ' ' x $item_indent .
218       qq(<comments>$rss20::trackback_link</comments>\n);
219   }
220   $blosxom::template{$flavour}{'story'} .= 
221       ' ' x $item_indent .
222       '$rss20::category_list';
223
224   # GeoRSS support
225   if ($blosxom::plugins{geo}) {
226     $blosxom::template{$flavour}{'story'} .= '$rss20::georss';
227   }
228
229   $blosxom::template{$flavour}{'story'} .= <<'STORY';
230 <description>$body
231             </description>
232         </item>
233 STORY
234
235   $blosxom::template{$flavour}{'foot'} = <<'FOOT';
236
237     </channel>
238 </rss>
239 FOOT
240
241   1;
242 }
243
244
245 1;
246
247 __END__
248
249 =head1 NAME
250
251 rss20 - blosxom plugin to generate an RSS 2.0 feed of your blog
252
253 =head1 DESCRIPTION
254
255 rss20 is a blosxom plugin to generate an RSS 2.0 feed of your blog. It
256 is self-contained, including the required flavours, and has a bunch of
257 configuration variables to allow for configuration.
258
259 If you're using the L<geo> plugin, rss20 will also add georss:point
260 entries for any items with latitude and longitude metadata set (see 
261 L<geo>).
262
263 =head2 CONFIGURATION
264
265 The following package variables can be configured:
266
267 =over 4
268
269 =item $flavour
270
271 Flavour string to use for your feed (typically 'rss' or 'rss20').
272
273 =item $author_email
274
275 Default author email address for posts.
276
277 =item $webmaster_email
278
279 Email address to use for webmaster responsible for the feed (defaults 
280 to $author_email).
281
282 =item $permalink
283
284 Story permalink. Default is '$url$path/$fn.$default_flavour'.
285 Note that this value should probably be single quoted to defer
286 variable evaluation until rendering time.
287
288 =item $trackback_link
289
290 Story trackback or comment link. Default is ''. Useful if you
291 are using a comments plugin like C<writeback> or C<feedback>,
292 and the format you want will be plugin-dependant.
293
294 Like $permalink, this value should be single quoted to defer
295 variable evaluation till rendering time.
296
297 =item $copyright
298
299 Default copyright clause for posts, if any.
300
301 =back
302
303 =head1 USAGE
304
305 rss20 should be loaded relatively late, since you'll typically want
306 plugins that manipulate your story content to have run already. It 
307 also should be run after the 'story' or 'prefs' plugins if you want
308 to use those to customise your configuration variables.
309
310 Requires the L<storydate> plugin for setting up story dates in the 
311 right formats, and recommends the L<absolute> plugin for absolutising
312 URLs.
313
314
315 =head1 SEE ALSO
316
317 L<storydate>, L<absolute>, L<geo>
318
319 Blosxom: http://blosxom.sourceforge.net/
320
321 rss20 is based on the 'atomfeed' and 'rss10' plugins, by Rael
322 Dornfest and contributors.
323
324
325 =head1 BUGS
326
327 Please report bugs either directly to the author or to the blosxom 
328 development mailing list: <blosxom-devel@lists.sourceforge.net>.
329
330
331 =head1 AUTHOR
332
333 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
334
335
336 =head1 LICENSE
337
338 Copyright 2007 Gavin Carr.
339
340 This plugin is licensed under the same terms as blosxom itself i.e.
341
342 Permission is hereby granted, free of charge, to any person obtaining a
343 copy of this software and associated documentation files (the "Software"),
344 to deal in the Software without restriction, including without limitation
345 the rights to use, copy, modify, merge, publish, distribute, sublicense,
346 and/or sell copies of the Software, and to permit persons to whom the
347 Software is furnished to do so, subject to the following conditions:
348
349 The above copyright notice and this permission notice shall be included
350 in all copies or substantial portions of the Software.
351
352 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
353 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
354 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
355 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
356 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
357 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
358 OTHER DEALINGS IN THE SOFTWARE.
359
360 =cut
361
362 # vim:ft=perl