doc/todo/fancypodcast/discussion.mdwn

   1 # Round 1
   2
   3 ikiwiki's simple podcasting, while elegant and minimal, doesn't (as
   4 mentioned in [[todo/blogging]]) produce full-featured feeds. In
   5 fancy podcasts, episodes are accompanied by text content. The feeds
   6 also have lots more metadata.
   7
   8 ## Design
   9
  10 7. For each fancy podcast episode, write a blog post containing
  11    `\[[!meta enclosure="WikiLink/to/media.mp3"]]`. (Don't specify
  12    more than one enclosure -- but if you do, last one wins.)
  13 7. When rendering to HTML (single-page or inlined), append a link
  14    to the media file.
  15 7. When rendering to RSS/Atom, the text is the entry's content and
  16    the media file is its enclosure.
  17 7. Don't break simple podcasts in pursuit of fancy podcasts.
  18
  19 ## Implementation
  20
  21 ### Completed
  22
  23 * Cover the existing simple podcast behavior with tests.
  24 * Add an `enclosure` field to [[plugins/meta]] that expands the
  25   given [[ikiwiki/WikiLink]] to an absolute URL (feed enclosures
  26   pretty much need to be, and the reference feeds I've looked at
  27   all do this).
  28 * Write failing tests for the desired single-page and inlined
  29   HTML behavior, then make them pass by adding enclosure stanzas
  30   to `{,inline}page.tmpl`.
  31 * Write failing tests for the desired RSS/Atom behavior, then make
  32   them pass via changes to `{atom,rss}item.tmpl` and [[plugins/inline]].
  33 * Match feature-for-feature with
  34   [tru_podcast](http://www.rainskit.com/blog/542/tru_podcast-a-podcasting-plugin-for-textpattern)
  35   (what [[schmonz]] will be migrating from).
  36 * Enrich [feed metadata](http://cyber.law.harvard.edu/rss/rss.html)
  37   by catching up `rsspage.tmpl` to `atompage.tmpl`.
  38 * Verify that [[plugins/more]] plays well with fancy podcasts.
  39 * Verify that the feeds validate.
  40 * Subscribe to a fancy feed in some common podcatchers and verify
  41   display details against a reference podcast.
  42 * Verify smooth transitions for two common use cases (see testing
  43   details below).
  44 * Code review: don't add enclosure divs unless we have enclosures.
  45 * Code review: genericize download link for more use cases.
  46 * Code review: don't confuse old readers with Atom names in RSS.
  47 * Code review: instead of hacking back to `$link`, just provide it.
  48 * Code review: show author in addition to feedname, if different.
  49
  50 ### Code review
  51
  52         +                               # XXX better way to compute relative to srcdir?
  53         +                               my $file = $absurl;
  54         +                               $file =~ s|^$config{url}/||;
  55
  56 I don't think ikiwiki offers a better way to do that, because there is
  57 normally no reason to do that. Why does it need an url of this form here?
  58 --[[Joey]]
  59
  60 > In all the popular, production-quality podcast feeds I've looked
  61 > at, enclosure URLs are always absolute (even when they could be
  62 > expressed concisely as relative). [Apple's
  63 > example](http://www.apple.com/itunes/podcasts/specs.html#example)
  64 > does too. So I told \[[!meta]] to call `urlto()` with the third
  65 > parameter true, which means the \[[!inline]] code here gets an
  66 > absolute URL in `$pagestate{$p}{meta}{enclosure}`. To compute the
  67 > enclosure's metadata, though, we of course need it as a local path.
  68 > I didn't see a less
  69 > [ongepotchket](http://www.jewish-languages.org/jewish-english-lexicon/words/1402)
  70 > way at the time. If you have a better idea, I'm happy to hear it;
  71 > if not, I'll add an explanatory comment. --[[schmonz]]
  72
  73 >> I would be more comfortable with this if two two different forms of url
  74 >> you need were both generated by calling urlto. It'd be fine to call
  75 >> it more than once. --[[Joey]]
  76
  77 >>> Heh, it was even easier than that! (Hooray for tests.) Done.
  78 >>> --[[schmonz]]
  79
  80         +<TMPL_IF HTML5><section id="inlineenclosure"><TMPL_ELSE><div id="inlineenclosure"></TMPL_IF>
  81         +<TMPL_IF ENCLOSURE>
  82
  83 Can't we avoid adding this div when there's no enclosure? --[[Joey]]
  84
  85 > Sure, I've moved the `<TMPL_IF ENCLOSURE>` check to outside the
  86 > section-and-div block for `{,inline}page.tmpl`. --[[schmonz]]
  87
  88         +<a href="<TMPL_VAR ENCLOSURE>">Download this episode</a>
  89
  90 "Download this episode" is pretty specific to particular use cases.
  91 Can this be made more generic, perhaps just "Download"? --[[Joey]]
  92
  93 > Yep, I got a little carried away. Done. --[[schmonz]]
  94
  95         -<TMPL_IF AUTHOR>
  96         -       <title><TMPL_VAR AUTHOR ESCAPE=HTML>: <TMPL_VAR TITLE></title>
  97         -       <dcterms:creator><TMPL_VAR AUTHOR ESCAPE=HTML></dcterms:creator>
  98
  99 This change removes the author name from the title of the rss feed, which
 100 does not seem necessary for fancy podcasts. And it is a change that
 101 could negatively impact eg, Planet style aggregators using ikiwiki. --[[Joey]]
 102
 103 > While comparing how feeds render in podcatchers, I noticed that
 104 > RSS and Atom were inconsistent in a couple ways, of which this was
 105 > one. The way I noticed it: with RSS, valuable title space was being
 106 > spent to display the author. I figured Atom's display was the one
 107 > worth matching. You're right, of course, that planets using the
 108 > default template and somehow relying on the current author-in-the-title
 109 > rendering for RSS feeds (but not Atom feeds!) would be broken by
 110 > this change. I'm having trouble imagining exactly what would break,
 111 > though, since guids and timestamps are unaffected. Would it suffice
 112 > to provide a note in the changelog warning people to be careful
 113 > upgrading their planets, and to customize `rssitem.tmpl` if they
 114 > really prefer the old behavior (or don't want to take any chances)?
 115 > --[[schmonz]]
 116
 117 >> A specific example I know of is updo.debian.net, when used with
 118 >> rss2email. Without the author name there, one cannot see who posted
 119 >> an item. It's worth noting that planet.debian.org does the same thing
 120 >> with its rss feed. (That's probably what I copied.) Atom feeds may
 121 >> not have this problem, don't know. --[[Joey]]
 122
 123 >>> Okay, that's easy to reproduce. It looks like this _might_ be
 124 >>> a simple matter of getting \[[!aggregate]] to populate author in
 125 >>> `add_page()`. I'll see what I can figure out. --[[schmonz]]
 126
 127 >>>> Yep, that was mostly it. If the feed entry defines an author,
 128 >>>> and the author is distinct from the feed name, we now show `NAME:
 129 >>>> AUTHOR`, else just show `NAME` (same as always). In addition,
 130 >>>> the W3 feed validator says `<dcterms:creator>` is invalid, so
 131 >>>> I replaced it with `<dc:creator>`, and all of a sudden `r2e`
 132 >>>> gives me better `From:` headers. With the latest on my branch,
 133 >>>> when I generate the same planet as updo and run `r2e` over it,
 134 >>>> the names I get in `From:` look like so:
 135
 136 *  `"updo: Junio C Hamano"`
 137 *  `"updo: Greg Kroah-Hartman"`
 138 *  `"updo: Eric Raymond: esr"` (article author != feed name, so we get both)
 139 *  `"updo: Jannis Pohlman: Jannis Pohlmann"` (oops! I tweaked the real updo)
 140
 141 >>>> --[[schmonz]]
 142
 143         +++ b/templates/rsspage.tmpl
 144         +       xmlns:atom="http://www.w3.org/2005/Atom"
 145         +<atom:link href="<TMPL_VAR FEEDURL>" rel="self" type="application/rss+xml" />
 146
 147 Why is it using atom namespace inside an rss feed? What are the chances
 148 every crummy rss reader on earth is going to understand this? I'd put it at
 149 about 0%; I doubt ikiwiki's own rss reader understands such a mashup.
 150 --[[Joey]]
 151
 152 > The validator I used (<http://validator.w3.org/feed/>) told me to.
 153 > Pretty sure it doesn't make anything work better in the podcatchers
 154 > I tried. Hadn't considered that it might break some readers.
 155 > Removed. --[[schmonz]]
 156
 157         +<generator>ikiwiki</generator>
 158
 159 Does this added tag provide any benefits? --[[Joey]]
 160
 161 > Consistency with the Atom feed, and of course it trumpets ikiwiki
 162 > to software and/or curious humans who inspect their feeds. The tag
 163 > arrived only in RSS 2.0, but that's already the version we're
 164 > claiming to be, and it's over a decade old. Seems much less risky
 165 > than the atom namespace bits. --[[schmonz]]
 166
 167 >> Sounds ok then. --[[Joey]]