.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "App::DocKnot::Spin::RSS 3pm"
.TH App::DocKnot::Spin::RSS 3pm "2022-01-20" "perl v5.32.1" "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"
App::DocKnot::Spin::RSS \- Generate RSS and thread from a feed description file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use App::DocKnot::Spin::RSS;
\&
\& my $rss = App::DocKnot::Spin::RSS\->new({ base => \*(Aqpath/to/tree\*(Aq });
\& $rss\->generate(\*(Aqpath/to/tree/.rss\*(Aq);
.Ve
.SH "REQUIREMENTS"
.IX Header "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 \s-1CPAN.\s0
.SH "DESCRIPTION"
.IX Header "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 \s-1RSS.\s0 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.
.PP
Output files are only regenerated if they are older than the input feed
description file.
.PP
App::DocKnot::Spin::RSS is designed for use with App::DocKnot::Spin. It
relies on App::DocKnot::Spin::Thread to convert thread to \s-1HTML,\s0 both for
inclusion in \s-1RSS\s0 feeds and for post-processing of generated thread files.
App::DocKnot::Spin::RSS is invoked automatically by App::DocKnot::Spin when it
encounters an \fI.rss\fR file in a directory it is processing.
.PP
See \*(L"\s-1INPUT LANGUAGE\*(R"\s0 for the details of the language in which \fI.rss\fR files
are written.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "new(\s-1ARGS\s0)" 4
.IX Item "new(ARGS)"
Create a new App::DocKnot::Spin::RSS object. \s-1ARGS\s0 should be a hash reference
with one or more of the following keys, all of which are optional:
.RS 4
.IP "base" 4
.IX Item "base"
By default, App::DocKnot::Spin::RSS output files are relative to the current
working directory. If the \f(CW\*(C`base\*(C'\fR argument is given, output files will be
relative to the value of \f(CW\*(C`base\*(C'\fR instead. Output files specified as absolute
paths will not be affected. \f(CW\*(C`base\*(C'\fR may be a string or a Path::Tiny object.
.RE
.RS 4
.RE
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.IP "generate(FILE[, \s-1BASE\s0])" 4
.IX Item "generate(FILE[, BASE])"
Parse the input file \s-1FILE\s0 and generate the output files that it specifies.
\&\s-1BASE,\s0 if given, specifies the root directory for output files specified with
relative paths, and overrides any \f(CW\*(C`base\*(C'\fR argument given to \fBnew()\fR. Both \s-1FILE\s0
and \s-1BASE\s0 may be strings or Path::Tiny objects.
.SH "INPUT LANGUAGE"
.IX Header "INPUT LANGUAGE"
The input for App::DocKnot::Spin::RSS is normally a \fI.rss\fR 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:
.PP
.Vb 2
\& Field: value
\& continuation of value
.Ve
.PP
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:
.PP
.Vb 3
\& Field: first paragraph
\& .
\& second paragraph
.Ve
.SS "Metadata"
.IX Subsection "Metadata"
The first block of the file sets the metadata for this set of output. The
following fields are supported:
.IP "Base" 4
.IX Item "Base"
The base \s-1URL\s0 for entries in this file. All links in subsequent blocks of the
file, if not absolute URLs, are treated as relative to this \s-1URL\s0 and are made
absolute by prepending this \s-1URL.\s0 Always specify this key unless all Link
fields in the remainder of the file use absolute URLs.
.Sp
This field value is also used as the \f(CW\*(C`\*(C'\fR element in the \s-1RSS\s0 feed,
indicating the web site corresponding to this feed.
.IP "Description" 4
.IX Item "Description"
The description of the feed, used only in the \s-1RSS\s0 output. This should always
be set if there are any \s-1RSS\s0 output files.
.IP "Index-Base" 4
.IX Item "Index-Base"
The base \s-1URL\s0 for output files of type \f(CW\*(C`index\*(C'\fR. This is used to canonicalize
relative URLs and should be the \s-1URL\s0 to the directory containing the \s-1HTML\s0 file
that will result from processing the thread output. This should be set if
there are any output files of type \f(CW\*(C`index\*(C'\fR; if it isn't set, relative links
may be rewritten incorrectly.
.IP "Index-Prefix" 4
.IX Item "Index-Prefix"
When generating output files of type \f(CW\*(C`index\*(C'\fR, use the value as the initial
content of the generated thread. This field should almost always be set if
any output files of type \f(CW\*(C`index\*(C'\fR are defined. It will contain such things as
the \f(CW\*(C`\eheading\*(C'\fR command, any prologue material, initial headings, and so
forth.
.IP "Index-Suffix" 4
.IX Item "Index-Suffix"
When generating output files of type \f(CW\*(C`index\*(C'\fR, append the value to the end of
the generated thread. The \f(CW\*(C`\esignature\*(C'\fR 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 \f(CW\*(C`\ediv\*(C'\fR commands).
.IP "Language" 4
.IX Item "Language"
The language of the feed, used only in the \s-1RSS\s0 output. This should always be
set if there are any \s-1RSS\s0 output files. Use \f(CW\*(C`en\-us\*(C'\fR for \s-1US\s0 English.
.IP "Output" 4
.IX Item "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.
.Sp
An output specifier is of the form \fItags\fR:\fItype\fR:\fIfile\fR, where \fIfile\fR is
the output file (always a relative path), \fItype\fR is the type of output, and
\&\fItags\fR indicates which entries to include in this file. \fItags\fR is a
comma-separated list of tags or the special value \f(CW\*(C`*\*(C'\fR, indicating all tags.
.Sp
There are three types of output:
.RS 4
.IP "index" 4
.IX Item "index"
Output thread containing all recent entries. This output file honors the
Recent field similar to \s-1RSS\s0 output and is used to generate something akin to a
journal or blog front page: an \s-1HTML\s0 version of all recent entries. It only
supports external entries (entries with \f(CW\*(C`Journal\*(C'\fR or \f(CW\*(C`Review\*(C'\fR fields). The
\&\f(CW\*(C`Index\-Base\*(C'\fR and \f(CW\*(C`Index\-Prefix\*(C'\fR (and possibly \f(CW\*(C`Index\-Suffix\*(C'\fR) fields should
be set.
.Sp
For output for entries with simple descriptions included in the input file,
see the \f(CW\*(C`thread\*(C'\fR output type.
.IP "rss" 4
.IX Item "rss"
Output an \s-1RSS\s0 file. App::DocKnot::Spin::RSS only understands the \s-1RSS 2.0\s0
output format. The \f(CW\*(C`Description\*(C'\fR, \f(CW\*(C`Language\*(C'\fR, \f(CW\*(C`RSS\-Base\*(C'\fR, and \f(CW\*(C`Title\*(C'\fR
fields should be set to provide additional metadata for the output file.
.IP "thread" 4
.IX Item "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 \f(CW\*(C`Thread\-Prefix\*(C'\fR field should be set.
.Sp
For output that can handle entries from external files, see the \f(CW\*(C`index\*(C'\fR
output type.
.RE
.RS 4
.RE
.IP "Recent" 4
.IX Item "Recent"
Sets the number of recent entries to include in output files of type \f(CW\*(C`rss\*(C'\fR or
\&\f(CW\*(C`index\*(C'\fR (but not \f(CW\*(C`thread\*(C'\fR, which will include the full contents of the
file). If this field is not present, the default is 15.
.IP "RSS-Base" 4
.IX Item "RSS-Base"
The base \s-1URL\s0 for \s-1RSS\s0 files generated by this file. Each generated \s-1RSS\s0 file
should have a link back to itself, and that link will be formed by taking the
output name and prepending this field.
.IP "Thread-Prefix" 4
.IX Item "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 \f(CW\*(C`thread\*(C'\fR are defined. It will contain such things
as the \f(CW\*(C`\eheading\*(C'\fR command, any prologue material, initial headings, and so
forth.
.IP "Title" 4
.IX Item "Title"
The title of the feed, used only in the \s-1RSS\s0 output. This should always be set
if there are any \s-1RSS\s0 output files.
.SS "Entries"
.IX Subsection "Entries"
After the first block, each subsequent block in the input file defines an
entry. Entries take the following fields:
.IP "Date" 4
.IX Item "Date"
The date of this entry in \s-1ISO\s0 date format (YYYY-MM-DD \s-1HH:MM\s0). This field is
required.
.IP "Description" 4
.IX Item "Description"
The inline contents of this entry. One and only one of this field,
\&\f(CW\*(C`Journal\*(C'\fR, or \f(CW\*(C`Review\*(C'\fR should be present. \f(CW\*(C`Description\*(C'\fR fields can only be
used with output types of \f(CW\*(C`rss\*(C'\fR or \f(CW\*(C`thread\*(C'\fR.
.IP "Journal" 4
.IX Item "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 \f(CW\*(C`\eh1\*(C'\fR and after the \f(CW\*(C`\edate\*(C'\fR macro, and
the \f(CW\*(C`\edate\*(C'\fR line is stripped off (the date information from the \f(CW\*(C`Date\*(C'\fR field
is used instead).
.Sp
One and only one of this field, \f(CW\*(C`Description\*(C'\fR, or \f(CW\*(C`Review\*(C'\fR should be
present.
.IP "Link" 4
.IX Item "Link"
The link to the page referenced by this entry. The link is relative to the
\&\f(CW\*(C`Base\*(C'\fR field set in the input file metadata. This field is required.
.IP "Review" 4
.IX Item "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.
.Sp
Many transformations are applied to entries of this sort based on the format
used by my book reviews and the \s-1URL\s0 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.
.Sp
One and only one of this field, \f(CW\*(C`Description\*(C'\fR, or \f(CW\*(C`Review\*(C'\fR should be
present.
.IP "Tags" 4
.IX Item "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 \f(CW\*(C`Review\*(C'\fR field will
automatically have the \f(CW\*(C`review\*(C'\fR tag.
.Sp
Entries may have no tags, in which case they're only included in output files
with a tag specification of \f(CW\*(C`*\*(C'\fR.
.IP "Title" 4
.IX Item "Title"
The title of the entry. This field is required.
.SH "NOTES"
.IX Header "NOTES"
\&\s-1RSS 2.0\s0 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
\&\s-1URL,\s0 something that I needed for an \s-1RSS\s0 feed of recent changes to my entire
site.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Allbery
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2008, 2010\-2012, 2021\-2022 Russ Allbery
.PP
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the \*(L"Software\*(R"), 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:
.PP
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
.PP
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\s0 \s-1IN 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.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdocknot\fR\|(1), App::DocKnot::Spin, App::DocKnot::Spin::Thread
.PP
This module is part of the App-DocKnot distribution. The current version of
DocKnot is available from \s-1CPAN,\s0 or directly from its web site at
.