spin-rss

(Generate RSS and thread from a feed description file)

SYNOPSIS

spin-rss [-hv] [-b base] file

REQUIREMENTS

Perl 5.006 or later and the Date::Parse module, which is part of the TimeDate distribution on CPAN. spin is required for anything other than simple entries with the text of the entry inline in the feed description file.

DESCRIPTION

spin-rss reads as input a feed description file consisting of simple key/value pairs and writes out either thread (for input to spin) 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.

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

OPTIONS

-b base, --base=base

By default, spin-rss output files are relative to the current working directory. If the -b option is given, output files will be relative to base instead. Output files specified as absolute paths will not be affected. spin always passes this option to spin-rss.

-h, --help

Print out this documentation (which is done simply by feeding the script to perldoc -t).

-v, --version

Print out the version of spin-rss and exit.

INPUT LANGUAGE

The input for spin-rss is normally a .rss file in a tree being processed by spin, but may be any file name passed to spin-rss. 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. 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 \class(date), and the \class(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 filel 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 ofo 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.

BUGS

The separate index and thread output types are a historical artifact and should be merged in some way. This will likely also require a way of configuring different caps on number of included entries in different output specifications.

The file format for review entries is not specified and involves a lot of ad hoc heuristics that work with my book review format.

Support for additional RSS standards would be nice, although in practice everything seems to be able to cope with RSS 2.0.

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.

SEE ALSO

spin(1)

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

Copyright 2008 Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Last spun 2013-07-01 from POD modified 2012-12-23