view release on metacpan or  search on metacpan

lib/App/DocKnot/Spin/RSS.pm  view on Meta::CPAN

            $self->_rss_output($file, $base, $metadata_ref, \@entries);
        } elsif ($format eq 'index') {
            if (scalar(@entries) > $metadata_ref->{recent}) {
                splice(@entries, $metadata_ref->{recent});
            }
            $self->_report_action('Generating index file', $file);
            my $index_base = $source->parent();
            $self->_index_output($file, $index_base, $metadata_ref, \@entries);
        }
    }
    return;
}

##############################################################################
# Module return value and documentation
##############################################################################

1;
__END__

=for stopwords
Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT RSS TimeDate YYYY-MM-DD
sublicense hoc rss

=head1 NAME

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

=head1 SYNOPSIS

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

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

=head1 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.

=head1 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 F<.rss> file in a directory it is processing.

See L<INPUT LANGUAGE> for the details of the language in which F<.rss> files
are written.

=head1 CLASS METHODS

=over 4

=item 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:

=over 4

=item base

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

=back

=back

=head1 INSTANCE METHODS

=over 4

=item 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 C<base> argument given to new().  Both FILE
and BASE may be strings or Path::Tiny objects.

=back

=head1 INPUT LANGUAGE

The input for App::DocKnot::Spin::RSS is normally a F<.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

=head2 Metadata

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

=over 4

=item 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 C<< <link> >> element in the RSS feed,
indicating the web site corresponding to this feed.

=item Description

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

=item Index-Base

The base URL for output files of type C<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 C<index>; if it isn't set, relative links
may be rewritten incorrectly.

=item Index-Prefix

When generating output files of type C<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 C<index> are defined.  It will contain such things as
the C<\heading> command, any prologue material, initial headings, and so
forth.

=item Index-Suffix

When generating output files of type C<index>, append the value to the end of
the generated thread.  The C<\signature> command is always appended and should