App::DocKnot::Spin::RSS - Generate RSS and thread from a feed description file

Author

       Russ Allbery <rra@cpan.org>

Class Methods

       new(ARGS)
           Create a new App::DocKnot::Spin::RSS object.  ARGS should be a hash reference with one or more of the
           following keys, all of which are optional:

           base
               By  default,  App::DocKnot::Spin::RSS output files are relative to the current working directory.
               If the "base" argument is given, output files will be relative to the value  of  "base"  instead.
               Output  files  specified  as  absolute  paths  will not be affected.  "base" may be a string or a
               Path::Tiny object.

Copyright And License

       Copyright 2008, 2010-2012, 2021-2022 Russ Allbery <rra@cpan.org>

       Permission is hereby granted, free of charge, to any  person  obtaining  a  copy  of  this  software  and
       associated  documentation  files (the "Software"), to deal in the Software without restriction, including
       without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,  and/or  sell
       copies  of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
       following conditions:

       The above copyright notice and this permission notice shall be included  in  all  copies  or  substantial
       portions of the Software.

       THE  SOFTWARE  IS  PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
       LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT.   IN
       NO  EVENT  SHALL  THE  AUTHORS  OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
       WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT  OF  OR  IN  CONNECTION  WITH  THE
       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Description

       App::DocKnot::Spin::RSS reads as input a feed description file consisting of simple key/value pairs and
       writes out either thread (for input to App::DocKnot::Spin::Thread) or RSS.  The feed description consists
       of a leading block of metadata and then one block per entry in the feed.  Each block can either include
       the content of the entry or can reference an external thread file, in several formats, for the content.
       The feed description file defines one or more output files in the Output field of the metadata.

       Output files are only regenerated if they are older than the input feed description file.

       App::DocKnot::Spin::RSS is designed for use with App::DocKnot::Spin.  It relies on
       App::DocKnot::Spin::Thread to convert thread to HTML, both for inclusion in RSS feeds and for post-
       processing of generated thread files.  App::DocKnot::Spin::RSS is invoked automatically by
       App::DocKnot::Spin when it encounters an .rss file in a directory it is processing.

       See "INPUT LANGUAGE" for the details of the language in which .rss files are written.

Input Language

The input for App::DocKnot::Spin::RSS is normally a .rss file in a tree being processed by
App::DocKnot::Spin. The file consists of one or more blocks of RFC-2822-style fields with values, each
separated by a blank line. Each field and value looks like an e-mail header field, including possible
continuation lines:

Field: value
continuation of value

Any line beginning with whitespace is considered a continuation of the previous line. If a value should
contain a blank line, indicate that blank line with a continuation line containing only a period. For
example:

Field: first paragraph
.
second paragraph

Metadata
The first block of the file sets the metadata for this set of output. The following fields are
supported:

Base
The base URL for entries in this file. All links in subsequent blocks of the file, if not absolute
URLs, are treated as relative to this URL and are made absolute by prepending this URL. Always
specify this key unless all Link fields in the remainder of the file use absolute URLs.

This field value is also used as the "<link>" element in the RSS feed, indicating the web site
corresponding to this feed.

Description
The description of the feed, used only in the RSS output. This should always be set if there are any
RSS output files.

Index-Base
The base URL for output files of type "index". This is used to canonicalize relative URLs and should
be the URL to the directory containing the HTML file that will result from processing the thread
output. This should be set if there are any output files of type "index"; if it isn't set, relative
links may be rewritten incorrectly.

Index-Prefix
When generating output files of type "index", use the value as the initial content of the generated
thread. This field should almost always be set if any output files of type "index" are defined. It
will contain such things as the "\heading" command, any prologue material, initial headings, and so
forth.

Index-Suffix
When generating output files of type "index", append the value to the end of the generated thread.
The "\signature" command is always appended and should not be included here. Set this field only if
there is other thread that needs to be appended (such as closing brackets for "\div" commands).

Language
The language of the feed, used only in the RSS output. This should always be set if there are any
RSS output files. Use "en-us" for US English.

Output
Specifies the output files for this input file in the form of a whitespace-separated list of output
specifiers. This field must always be set.

An output specifier is of the form tags:type:file, where file is the output file (always a relative
path), type is the type of output, and tags indicates which entries to include in this file. tags is
a comma-separated list of tags or the special value "*", indicating all tags.

There are three types of output:

index
Output thread containing all recent entries. This output file honors the Recent field similar to
RSS output and is used to generate something akin to a journal or blog front page: an HTML
version of all recent entries. It only supports external entries (entries with "Journal" or
"Review" fields). The "Index-Base" and "Index-Prefix" (and possibly "Index-Suffix") fields
should be set.

For output for entries with simple descriptions included in the input file, see the "thread"
output type.

rss Output an RSS file. App::DocKnot::Spin::RSS only understands the RSS 2.0 output format. The
"Description", "Language", "RSS-Base", and "Title" fields should be set to provide additional
metadata for the output file.

thread
Output thread containing all entries in this input file. This should only be used for input
files where all entries have their description text inline in the input file. Every entry will
be included. The output will be divided into sections by month, and each entry will be in a
description list, with the title prefixed by the date. The "Thread-Prefix" field should be set.

For output that can handle entries from external files, see the "index" output type.

Recent
Sets the number of recent entries to include in output files of type "rss" or "index" (but not
"thread", which will include the full contents of the file). If this field is not present, the
default is 15.

RSS-Base
The base URL for RSS files generated by this file. Each generated RSS file should have a link back
to itself, and that link will be formed by taking the output name and prepending this field.

Thread-Prefix
When generating thread output from this file, use the value as the initial content of the generated
thread. This field should almost always be set if any output files of type "thread" are defined. It
will contain such things as the "\heading" command, any prologue material, initial headings, and so
forth.

Title
The title of the feed, used only in the RSS output. This should always be set if there are any RSS
output files.

Entries
After the first block, each subsequent block in the input file defines an entry. Entries take the
following fields:

Date
The date of this entry in ISO date format (YYYY-MM-DD HH:MM). This field is required.

Description
The inline contents of this entry. One and only one of this field, "Journal", or "Review" should be
present. "Description" fields can only be used with output types of "rss" or "thread".

Journal
Specifies that the content of this entry should be read from an external thread file given by the
value of this field. The contents of that file are expected to be in the thread format used by my
journal entries: specifically, everything is ignored up to the first "\h1" and after the "\date"
macro, and the "\date" line is stripped off (the date information from the "Date" field is used
instead).

One and only one of this field, "Description", or "Review" should be present.

Link
The link to the page referenced by this entry. The link is relative to the "Base" field set in the
input file metadata. This field is required.

Review
Specifies that the content of this entry should be read from an external thread file given by the
value of this field. The contents of that file are expected to be in the thread format used by my
book reviews.

Many transformations are applied to entries of this sort based on the format used by my book reviews
and the URL layout they use, none of which is documented at present. For the time being, see the
source code for what transformations are done. This support will require modification for use by
anyone else.

One and only one of this field, "Description", or "Review" should be present.

Tags
Whitespace-separated tags for this entry, used to determine whether this entry will be included in a
given output file given its output specification. In addition to any tags listed here, any entry
with a "Review" field will automatically have the "review" tag.

Entries may have no tags, in which case they're only included in output files with a tag
specification of "*".

Title
The title of the entry. This field is required.

Instance Methods

       generate(FILE[, BASE])
           Parse the input file FILE and generate the output files that it specifies.  BASE, if given, specifies
           the root directory for output files specified with relative paths, and overrides any "base"  argument
           given to new().  Both FILE and BASE may be strings or Path::Tiny objects.

Name

       App::DocKnot::Spin::RSS - Generate RSS and thread from a feed description file

Notes

       RSS 2.0 was chosen as the output format because it supports GUIDs for entries  separate  from  the  entry
       URLs  and  hence  supports  multiple entries for the same URL, something that I needed for an RSS feed of
       recent changes to my entire site.

Requirements

       Perl 5.24 or later and the modules Date::Language, Date::Parse (both part of the TimeDate distribution),
       List::SomeUtils, Path::Tiny, and Perl6::Slurp, both of which are available from CPAN.

Synopsis

           use App::DocKnot::Spin::RSS;

           my $rss = App::DocKnot::Spin::RSS->new({ base => 'path/to/tree' });
           $rss->generate('path/to/tree/.rss');