view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

info, warn, error, and fatal.

# LICENSE

GNU Affero General Public License

# INSTALLATION

Using `cpan`:

    cpan App::jupiter

Manual install:

    perl Makefile.PL
    make
    make install

## Dependencies

To run Jupiter on Debian we need:

`libmodern-perl-perl` for [Modern::Perl](https://metacpan.org/pod/Modern%3A%3APerl)

`libmojolicious-perl` for [Mojo::Template](https://metacpan.org/pod/Mojo%3A%3ATemplate), [Mojo::UserAgent](https://metacpan.org/pod/Mojo%3A%3AUserAgent), [Mojo::Log](https://metacpan.org/pod/Mojo%3A%3ALog),
[Mojo::JSON](https://metacpan.org/pod/Mojo%3A%3AJSON), and [Mojo::Util](https://metacpan.org/pod/Mojo%3A%3AUtil)

`libxml-libxml-perl` for [XML::LibXML](https://metacpan.org/pod/XML%3A%3ALibXML)

`libfile-slurper-perl` for [File::Slurper](https://metacpan.org/pod/File%3A%3ASlurper)

`libdatetime-perl` for [DateTime](https://metacpan.org/pod/DateTime)

`libdatetime-format-mail-perl` for [DateTime::Format::Mail](https://metacpan.org/pod/DateTime%3A%3AFormat%3A%3AMail)

`libdatetime-format-iso8601-perl` for [DateTime::Format::ISO8601](https://metacpan.org/pod/DateTime%3A%3AFormat%3A%3AISO8601)

Unfortunately, [Mojo::UserAgent::Role::Queued](https://metacpan.org/pod/Mojo%3A%3AUserAgent%3A%3ARole%3A%3AQueued) isn't packaged for Debian.
Therefore, let's build it and install it as a Debian package.

    sudo apt-get install libmodule-build-tiny-perl
    sudo apt-get install dh-make-perl
    sudo dh-make-perl --build --cpan Mojo::UserAgent::Role::Queued
    dpkg --install libmojo-useragent-role-queued-perl_1.15-1_all.deb

To generate the `README.md` from the source file, you need `pod2markdown`
which you get in `libpod-markdown-perl`.

# FILES

There are a number of files in the `share` directory which you can use as
starting points.

`template.html` is the HTML template.

`default.css` is a small CSS file used by `template.html`.

`personalize.js` is a small Javascript file used by `template.html` used to
allow visitors to jump from one article to the next using `J` and `K`.

`jupiter.png` is used by `template.html` as the icon.

`jupiter.svg` is used by `template.html` as the logo.

`feed.png` is used by `template.html` as the icon for the feeds in the
sidebar.

`feed.rss` is the feed template.

# OPTIONS

HTML generation uses a template, `template.html`. It is written for
`Mojo::Template` and you can find it in the `share` directory of your
distribution. The default templates use other files, such as the logo, the feed
icon, a CSS file, and a small Javascript snippet to enable navigation using the
`J` and `K` keys (see above).

You can specify a different HTML file to generate:

**jupiter html** _your.html feed.opml_

If you specify two HTML files, the first is the HTML file to generate and the
second is the template to use. Both must use the `.html` extension.

**jupiter html** _your.html your-template.html feed.opml_

Feed generation uses a template, `feed.rss`. It writes all the entries into a
file called `feed.xml`. Again, the template is written for `Mojo::Template`.

You can specify up to two XML, RSS or ATOM files. They must uses one of these
three extensions: `.xml`, `.rss`, or `.atom`. The first is the name of the
feed to generate, the second is the template to use:

**jupiter html** _atom.xml template.xml planet.html template.html feed.opml_

In the above case, Planet Jupiter will write a feed called `atom.xml` based on
`template.xml` and a HTML file called `planet.html` based on `template.html`,
using the cached entries matching the feeds in `feed.opml`.

# TEMPLATES

The page template is called with three hash references: `globals`, `feeds`,
and `entries`. The keys of these three hash references are documented below.
The values of these hashes are all _escaped HTML_ except where noted (dates and
file names, for example).

The technical details of how to write the templates are documented in the man
page for [Mojo::Template](https://metacpan.org/pod/Mojo%3A%3ATemplate).

## Globals

There are not many global keys.

**date** is the the publication date of the HTML page, in ISO date format:
YYYY-MM-DD.

**files** is the list of OPML files used.

## Writing templates for feeds

Feeds have the following keys available:

**title** is the title of the feed.

**url** is the URL of the feed (RSS or Atom). This is not the link to the site!