.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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" '' . ds C` . ds C' '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 >0, 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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "PERLANET 1p" .TH PERLANET 1p "2023-02-21" "perl v5.36.0" "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" perlanet \- command line interface to Perlanet.pm .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& $ perlanet .Ve .PP Or .PP .Vb 1 \& $ perlanet config_file .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`perlanet\*(C'\fR is a command line program for aggregating web feeds (both Atom and \s-1RSS\s0) and publishing a new web page and a new web feed containing the results of that aggregation. .SH "COMMAND LINE ARGUMENTS" .IX Header "COMMAND LINE ARGUMENTS" \&\f(CW\*(C`perlanet\*(C'\fR takes one optional command line argument, which is the name of a configuration file to use. If no filename is given then the program looks for a file called \f(CW\*(C`perlanetrc\*(C'\fR in the current directory. .SH "CONFIGURATION FILE" .IX Header "CONFIGURATION FILE" \&\f(CW\*(C`perlanet\*(C'\fR requires a configuration file which contains details of which feeds to aggregate and what to do with the results of the aggregation. By default, \f(CW\*(C`perlanet\*(C'\fR looks for a file called \f(CW\*(C`perlanetrc\*(C'\fR in the current directory, but this name can be overridden by passing the name of a different file when calling the program. .PP The configuration file is in \s-1YAML\s0 format. \s-1YAML\s0 is a simple text-based file format. See for further details. .SS "Configuration Options" .IX Subsection "Configuration Options" The configuration file can contain the following options. .IP "title" 4 .IX Item "title" The title of the resulting page and web feed. This option is mandatory. .IP "description" 4 .IX Item "description" The description of the resulting page and web feed. This option is mandatory. .IP "url" 4 .IX Item "url" A \s-1URL\s0 which will be associated with the resulting page and web feed. This will usually be the address where the web page will be published. This option is mandatory. .IP "author" 4 .IX Item "author" The name and email address of the author of the aggregated content. This item has two sub-items \- one each for the name and email address. This option is mandatory. .IP "agent" 4 .IX Item "agent" This optional entry defines the agent string that perlanet will use when requesting data from web sites. It's the name of the program that site owners will see in their web site access logs. Although it is optional, it is strongly recommended that you give a value for this configuration option and that the value you use includes contact details so that web site owners can get in touch with you if they have any concerns about your use of their site. .IP "entries" 4 .IX Item "entries" The maximum number of entries to include in the aggregated content. This option is mandatory. .IP "entries_per_feed" 4 .IX Item "entries_per_feed" The \f(CW\*(C`entries\*(C'\fR value above defines the total number of entries in the aggregated output feed. The value defines the number of entries to take from each of your source feeds. For example, if this is set to 1 then there will only be one entry from each feed in your output. If this value is 0 (or missing) then all values from all source feeds are used. .IP "entry_sort_order" 4 .IX Item "entry_sort_order" Entries have two dates, issued (which is the date that the item was first published) and modified (which is the date that the item was last updated). This configuration option controls which of these two dates are used to sort the entries in a feed. It can be one of the two values \f(CW\*(C`issued\*(C'\fR or \&\f(CW\*(C`modified\*(C'\fR. If this option is omitted, then \f(CW\*(C`modified\*(C'\fR is used. .IP "cutoff_duration" 4 .IX Item "cutoff_duration" Sometimes you might want your generated feed to only contain entries from, say, the last month. You can do that with the \f(CW\*(C`cutoff_duration\*(C'\fR configuration option. This takes the form of sub-parameters which are in the same format as you would use when calling the constructor for DateTime::Duration (which isn't surprising as that's what happens to them). For example the to exclude entries that are more than a month old, you would use: .Sp .Vb 2 \& cutoff_duration: \& months: 1 .Ve .IP "opml" 4 .IX Item "opml" The system can optionally create an \s-1OPML\s0 file containing details of the feeds which are being aggregated. This optional option controls whether or not this file is created. If it exists, it should be the name of the \s-1OPML\s0 file to be created. If an \s-1OPML\s0 file is being created, then the \f(CW\*(C`feeds\*(C'\fR options (described below) will all require a \f(CW\*(C`web\*(C'\fR sub-option. .IP "page" 4 .IX Item "page" This mandatory option contains the details of the web page to be created. There are two sub-options \- \f(CW\*(C`file\*(C'\fR gives the name of the file to be created and \f(CW\*(C`template\*(C'\fR gives the name of a Template Toolkit template which will be processed in order to create this file. See the section \*(L"Output Template\*(R" for more details on this template, and the web site for more information about the Template Toolkit. .IP "feed" 4 .IX Item "feed" This mandatory option contains the details of the web feed to be created. There are two sub-options \- \f(CW\*(C`file\*(C'\fR gives the name of the file to be created and \f(CW\*(C`format\*(C'\fR gives the format of the output (currently 'Atom' or '\s-1RSS\s0'). .IP "cache_dir" 4 .IX Item "cache_dir" This if you give a directory name in this option then perlanet will use the cache facility of URI::Fetch. This means that web feeds will only be downloaded when they change. .IP "feeds" 4 .IX Item "feeds" This mandatory option gives details of the web feeds to be aggregated. Each item on the list has one mandatory sub-option and two optional sub-options. The mandatory sub-option is \f(CW\*(C`url\*(C'\fR which gives the \s-1URL\s0 of the feed. The optional sub-option \f(CW\*(C`title\*(C'\fR gives a title to the feed which can be used to identify the entries that originate from this feed. The optional \f(CW\*(C`web\*(C'\fR sub-option gives a web site \s-1URL\s0 associated with the feed (often the address of the web site that the feed comes from). This can be used to create a list of the aggregated sites. The \f(CW\*(C`web\*(C'\fR sub-option becomes mandatory if you are creating an \s-1OPML\s0 file. You can also add a \f(CW\*(C`max_entries\*(C'\fR option which will override the global \f(CW\*(C`entries_per_feed\*(C'\fR setting. If this setting exists and is set to zero, then the output feed will contain all of the entries from this input feed. .SS "Example Configuration File" .IX Subsection "Example Configuration File" .Vb 10 \& title: planet test \& description: A Test Planet \& url: http://planet.example.com/ \& author: \& name: Dave Cross \& email: dave@dave.org.uk \& entries: 20 \& opml: opml.xml \& page: \& file: index.html \& template: index.tt \& feed: \& file: atom.xml \& format: Atom \& cache_dir: /tmp/feeds \& feeds: \& \- url: http://blog.dave.org.uk/atom.xml \& title: Dave\*(Aqs Blog \& web: http://blog.dave.org.uk/ \& \- url: http://use.perl.org/~davorg/journal/rss \& title: Dave\*(Aqs use.perl Journal \& web: http://use.perl.org/~davorg/journal/ \& \- url: http://www.oreillynet.com/pub/feed/31?au=2607 \& title: Dave on O\*(AqReillynet \& web: http://www.oreillynet.com/pub/au/2607 .Ve .SS "Output Template" .IX Subsection "Output Template" The web page is created from a Template Toolkit template. This template is passed two variables. .IP "feed" 4 .IX Item "feed" This is the XML::Feed object which has been used to create the aggregated feed. See the XML::Feed documentation for details of the data that is held in this object. .IP "cfg" 4 .IX Item "cfg" This is the contents of the configuration file, converted to a (nested) Perl hash. .SS "Example Output Template" .IX Subsection "Example Output Template" This is a simple template which uses the \f(CW\*(C`feed\*(C'\fR variable to display details of the aggregated feeds. .PP .Vb 10 \& \& \& \& \& \& [% feed.title %] \& \& \&

[% feed.title | html %]

\&

[% feed.description | html %]

\& [% FOREACH entry IN feed.entries %] \&

[% entry.title | html %]

\& [% entry.content.body %] \& [% IF entry.author OR entry.issued %] \&

Published[% IF entry.author %] by [% entry.author | html; END %] \& [% IF entry.issued %] on [% entry.issued | html; END %]

\& [% END %] \& [% END %] \&
\&
[% feed.author | html %] / [% feed.modified | html %]
\& \& .Ve .PP In the future, the Perlanet wiki at will contain a cookbook of useful ideas to include in the output template. .SH "SUPPORT" .IX Header "SUPPORT" To report bugs in Perlanet, please use the \s-1CPAN\s0 request tracker. You can either use the web page at or send an email to bug\-Perlanet@rt.cpan.org. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 perlanet .IP "\(bu" 4 Plagger .SH "AUTHOR" .IX Header "AUTHOR" Dave Cross, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2008 by Magnum Solutions Ltd. .PP This program library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.