diff options
| -rw-r--r-- | doc/todo/fancypodcast.mdwn | 171 | ||||
| -rw-r--r-- | doc/todo/fancypodcast/discussion.mdwn | 162 |
2 files changed, 163 insertions, 170 deletions
diff --git a/doc/todo/fancypodcast.mdwn b/doc/todo/fancypodcast.mdwn index 04d86823c..bff509325 100644 --- a/doc/todo/fancypodcast.mdwn +++ b/doc/todo/fancypodcast.mdwn @@ -10,10 +10,7 @@ also have lots more metadata. [[!template id=gitbranch branch=schmonz/fancypodcast author="[[schmonz]]"]] [[!tag patch]] -In summary, the branch preserves ikiwiki's existing podcast behavior, -adds more featureful behavior, and has been tested to work well in -some common podcatchers. I believe it is ready for integration. ---[[schmonz]] +Nothing new on the branch since 2013/07/21 merge to `master`. ## Features @@ -34,53 +31,6 @@ Episode description|(./) |(./) |(./) | Episode enclosure |(./) |(./) |(./) |(./) """]] -## Design - -7. For each fancy podcast episode, write a blog post containing - `\[[!meta enclosure="WikiLink/to/media.mp3"]]`. (Don't specify - more than one enclosure -- but if you do, last one wins.) -7. When rendering to HTML (single-page or inlined), append a link - to the media file. -7. When rendering to RSS/Atom, the text is the entry's content and - the media file is its enclosure. -7. Don't break simple podcasts in pursuit of fancy podcasts. - -## Implementation - -### Completed - -* Cover the existing simple podcast behavior with tests. -* Add an `enclosure` field to [[plugins/meta]] that expands the - given [[ikiwiki/WikiLink]] to an absolute URL (feed enclosures - pretty much need to be, and the reference feeds I've looked at - all do this). -* Write failing tests for the desired single-page and inlined - HTML behavior, then make them pass by adding enclosure stanzas - to `{,inline}page.tmpl`. -* Write failing tests for the desired RSS/Atom behavior, then make - them pass via changes to `{atom,rss}item.tmpl` and [[plugins/inline]]. -* Match feature-for-feature with - [tru_podcast](http://www.rainskit.com/blog/542/tru_podcast-a-podcasting-plugin-for-textpattern) - (what [[schmonz]] will be migrating from). -* Enrich [feed metadata](http://cyber.law.harvard.edu/rss/rss.html) - by catching up `rsspage.tmpl` to `atompage.tmpl`. -* Verify that [[plugins/more]] plays well with fancy podcasts. -* Verify that the feeds validate. -* Subscribe to a fancy feed in some common podcatchers and verify - display details against a reference podcast. -* Verify smooth transitions for two common use cases (see testing - details below). -* Code review: don't add enclosure divs unless we have enclosures. -* Code review: genericize download link for more use cases. -* Code review: don't confuse old readers with Atom names in RSS. -* Code review: instead of hacking back to `$link`, just provide it. -* Code review: show author in addition to feedname, if different. - -### Must-have (for [[schmonz]], anyway) - -* Think carefully about UTF-8. -* Verify that _all_ the tests pass (not just my new ones). - ## Migration ### Upgrading within ikiwiki: from simple to fancy @@ -228,125 +178,6 @@ it with ikiwiki instead. iTunes) alongside the RSS/Atom ones in [[plugins/inline]]. * Support Apple's "enhanced podcasts" (if they're still relevant). -### code review - - + # XXX better way to compute relative to srcdir? - + my $file = $absurl; - + $file =~ s|^$config{url}/||; - -I don't think ikiwiki offers a better way to do that, because there is -normally no reason to do that. Why does it need an url of this form here? ---[[Joey]] - -> In all the popular, production-quality podcast feeds I've looked -> at, enclosure URLs are always absolute (even when they could be -> expressed concisely as relative). [Apple's -> example](http://www.apple.com/itunes/podcasts/specs.html#example) -> does too. So I told \[[!meta]] to call `urlto()` with the third -> parameter true, which means the \[[!inline]] code here gets an -> absolute URL in `$pagestate{$p}{meta}{enclosure}`. To compute the -> enclosure's metadata, though, we of course need it as a local path. -> I didn't see a less -> [ongepotchket](http://www.jewish-languages.org/jewish-english-lexicon/words/1402) -> way at the time. If you have a better idea, I'm happy to hear it; -> if not, I'll add an explanatory comment. --[[schmonz]] - ->> I would be more comfortable with this if two two different forms of url ->> you need were both generated by calling urlto. It'd be fine to call ->> it more than once. --[[Joey]] - ->>> Heh, it was even easier than that! (Hooray for tests.) Done. ->>> --[[schmonz]] - - +<TMPL_IF HTML5><section id="inlineenclosure"><TMPL_ELSE><div id="inlineenclosure"></TMPL_IF> - +<TMPL_IF ENCLOSURE> - -Can't we avoid adding this div when there's no enclosure? --[[Joey]] - -> Sure, I've moved the `<TMPL_IF ENCLOSURE>` check to outside the -> section-and-div block for `{,inline}page.tmpl`. --[[schmonz]] - - +<a href="<TMPL_VAR ENCLOSURE>">Download this episode</a> - -"Download this episode" is pretty specific to particular use cases. -Can this be made more generic, perhaps just "Download"? --[[Joey]] - -> Yep, I got a little carried away. Done. --[[schmonz]] - - -<TMPL_IF AUTHOR> - - <title><TMPL_VAR AUTHOR ESCAPE=HTML>: <TMPL_VAR TITLE></title> - - <dcterms:creator><TMPL_VAR AUTHOR ESCAPE=HTML></dcterms:creator> - -This change removes the author name from the title of the rss feed, which -does not seem necessary for fancy podcasts. And it is a change that -could negatively impact eg, Planet style aggregators using ikiwiki. --[[Joey]] - -> While comparing how feeds render in podcatchers, I noticed that -> RSS and Atom were inconsistent in a couple ways, of which this was -> one. The way I noticed it: with RSS, valuable title space was being -> spent to display the author. I figured Atom's display was the one -> worth matching. You're right, of course, that planets using the -> default template and somehow relying on the current author-in-the-title -> rendering for RSS feeds (but not Atom feeds!) would be broken by -> this change. I'm having trouble imagining exactly what would break, -> though, since guids and timestamps are unaffected. Would it suffice -> to provide a note in the changelog warning people to be careful -> upgrading their planets, and to customize `rssitem.tmpl` if they -> really prefer the old behavior (or don't want to take any chances)? -> --[[schmonz]] - ->> A specific example I know of is updo.debian.net, when used with ->> rss2email. Without the author name there, one cannot see who posted ->> an item. It's worth noting that planet.debian.org does the same thing ->> with its rss feed. (That's probably what I copied.) Atom feeds may ->> not have this problem, don't know. --[[Joey]] - ->>> Okay, that's easy to reproduce. It looks like this _might_ be ->>> a simple matter of getting \[[!aggregate]] to populate author in ->>> `add_page()`. I'll see what I can figure out. --[[schmonz]] - ->>>> Yep, that was mostly it. If the feed entry defines an author, ->>>> and the author is distinct from the feed name, we now show `NAME: ->>>> AUTHOR`, else just show `NAME` (same as always). In addition, ->>>> the W3 feed validator says `<dcterms:creator>` is invalid, so ->>>> I replaced it with `<dc:creator>`, and all of a sudden `r2e` ->>>> gives me better `From:` headers. With the latest on my branch, ->>>> when I generate the same planet as updo and run `r2e` over it, ->>>> the names I get in `From:` look like so: - -* `"updo: Junio C Hamano"` -* `"updo: Greg Kroah-Hartman"` -* `"updo: Eric Raymond: esr"` (article author != feed name, so we get both) -* `"updo: Jannis Pohlman: Jannis Pohlmann"` (oops! I tweaked the real updo) - ->>>> --[[schmonz]] - - +++ b/templates/rsspage.tmpl - + xmlns:atom="http://www.w3.org/2005/Atom" - +<atom:link href="<TMPL_VAR FEEDURL>" rel="self" type="application/rss+xml" /> - -Why is it using atom namespace inside an rss feed? What are the chances -every crummy rss reader on earth is going to understand this? I'd put it at -about 0%; I doubt ikiwiki's own rss reader understands such a mashup. ---[[Joey]] - -> The validator I used (<http://validator.w3.org/feed/>) told me to. -> Pretty sure it doesn't make anything work better in the podcatchers -> I tried. Hadn't considered that it might break some readers. -> Removed. --[[schmonz]] - - +<generator>ikiwiki</generator> - -Does this added tag provide any benefits? --[[Joey]] - -> Consistency with the Atom feed, and of course it trumpets ikiwiki -> to software and/or curious humans who inspect their feeds. The tag -> arrived only in RSS 2.0, but that's already the version we're -> claiming to be, and it's over a decade old. Seems much less risky -> than the atom namespace bits. --[[schmonz]] - ->> Sounds ok then. --[[Joey]] - ---- [[merged|done]] --[[Joey]] diff --git a/doc/todo/fancypodcast/discussion.mdwn b/doc/todo/fancypodcast/discussion.mdwn new file mode 100644 index 000000000..bb225f89c --- /dev/null +++ b/doc/todo/fancypodcast/discussion.mdwn @@ -0,0 +1,162 @@ +# Round 1 + +## Design + +7. For each fancy podcast episode, write a blog post containing + `\[[!meta enclosure="WikiLink/to/media.mp3"]]`. (Don't specify + more than one enclosure -- but if you do, last one wins.) +7. When rendering to HTML (single-page or inlined), append a link + to the media file. +7. When rendering to RSS/Atom, the text is the entry's content and + the media file is its enclosure. +7. Don't break simple podcasts in pursuit of fancy podcasts. + +## Implementation + +### Completed + +* Cover the existing simple podcast behavior with tests. +* Add an `enclosure` field to [[plugins/meta]] that expands the + given [[ikiwiki/WikiLink]] to an absolute URL (feed enclosures + pretty much need to be, and the reference feeds I've looked at + all do this). +* Write failing tests for the desired single-page and inlined + HTML behavior, then make them pass by adding enclosure stanzas + to `{,inline}page.tmpl`. +* Write failing tests for the desired RSS/Atom behavior, then make + them pass via changes to `{atom,rss}item.tmpl` and [[plugins/inline]]. +* Match feature-for-feature with + [tru_podcast](http://www.rainskit.com/blog/542/tru_podcast-a-podcasting-plugin-for-textpattern) + (what [[schmonz]] will be migrating from). +* Enrich [feed metadata](http://cyber.law.harvard.edu/rss/rss.html) + by catching up `rsspage.tmpl` to `atompage.tmpl`. +* Verify that [[plugins/more]] plays well with fancy podcasts. +* Verify that the feeds validate. +* Subscribe to a fancy feed in some common podcatchers and verify + display details against a reference podcast. +* Verify smooth transitions for two common use cases (see testing + details below). +* Code review: don't add enclosure divs unless we have enclosures. +* Code review: genericize download link for more use cases. +* Code review: don't confuse old readers with Atom names in RSS. +* Code review: instead of hacking back to `$link`, just provide it. +* Code review: show author in addition to feedname, if different. + +### Code review + + + # XXX better way to compute relative to srcdir? + + my $file = $absurl; + + $file =~ s|^$config{url}/||; + +I don't think ikiwiki offers a better way to do that, because there is +normally no reason to do that. Why does it need an url of this form here? +--[[Joey]] + +> In all the popular, production-quality podcast feeds I've looked +> at, enclosure URLs are always absolute (even when they could be +> expressed concisely as relative). [Apple's +> example](http://www.apple.com/itunes/podcasts/specs.html#example) +> does too. So I told \[[!meta]] to call `urlto()` with the third +> parameter true, which means the \[[!inline]] code here gets an +> absolute URL in `$pagestate{$p}{meta}{enclosure}`. To compute the +> enclosure's metadata, though, we of course need it as a local path. +> I didn't see a less +> [ongepotchket](http://www.jewish-languages.org/jewish-english-lexicon/words/1402) +> way at the time. If you have a better idea, I'm happy to hear it; +> if not, I'll add an explanatory comment. --[[schmonz]] + +>> I would be more comfortable with this if two two different forms of url +>> you need were both generated by calling urlto. It'd be fine to call +>> it more than once. --[[Joey]] + +>>> Heh, it was even easier than that! (Hooray for tests.) Done. +>>> --[[schmonz]] + + +<TMPL_IF HTML5><section id="inlineenclosure"><TMPL_ELSE><div id="inlineenclosure"></TMPL_IF> + +<TMPL_IF ENCLOSURE> + +Can't we avoid adding this div when there's no enclosure? --[[Joey]] + +> Sure, I've moved the `<TMPL_IF ENCLOSURE>` check to outside the +> section-and-div block for `{,inline}page.tmpl`. --[[schmonz]] + + +<a href="<TMPL_VAR ENCLOSURE>">Download this episode</a> + +"Download this episode" is pretty specific to particular use cases. +Can this be made more generic, perhaps just "Download"? --[[Joey]] + +> Yep, I got a little carried away. Done. --[[schmonz]] + + -<TMPL_IF AUTHOR> + - <title><TMPL_VAR AUTHOR ESCAPE=HTML>: <TMPL_VAR TITLE></title> + - <dcterms:creator><TMPL_VAR AUTHOR ESCAPE=HTML></dcterms:creator> + +This change removes the author name from the title of the rss feed, which +does not seem necessary for fancy podcasts. And it is a change that +could negatively impact eg, Planet style aggregators using ikiwiki. --[[Joey]] + +> While comparing how feeds render in podcatchers, I noticed that +> RSS and Atom were inconsistent in a couple ways, of which this was +> one. The way I noticed it: with RSS, valuable title space was being +> spent to display the author. I figured Atom's display was the one +> worth matching. You're right, of course, that planets using the +> default template and somehow relying on the current author-in-the-title +> rendering for RSS feeds (but not Atom feeds!) would be broken by +> this change. I'm having trouble imagining exactly what would break, +> though, since guids and timestamps are unaffected. Would it suffice +> to provide a note in the changelog warning people to be careful +> upgrading their planets, and to customize `rssitem.tmpl` if they +> really prefer the old behavior (or don't want to take any chances)? +> --[[schmonz]] + +>> A specific example I know of is updo.debian.net, when used with +>> rss2email. Without the author name there, one cannot see who posted +>> an item. It's worth noting that planet.debian.org does the same thing +>> with its rss feed. (That's probably what I copied.) Atom feeds may +>> not have this problem, don't know. --[[Joey]] + +>>> Okay, that's easy to reproduce. It looks like this _might_ be +>>> a simple matter of getting \[[!aggregate]] to populate author in +>>> `add_page()`. I'll see what I can figure out. --[[schmonz]] + +>>>> Yep, that was mostly it. If the feed entry defines an author, +>>>> and the author is distinct from the feed name, we now show `NAME: +>>>> AUTHOR`, else just show `NAME` (same as always). In addition, +>>>> the W3 feed validator says `<dcterms:creator>` is invalid, so +>>>> I replaced it with `<dc:creator>`, and all of a sudden `r2e` +>>>> gives me better `From:` headers. With the latest on my branch, +>>>> when I generate the same planet as updo and run `r2e` over it, +>>>> the names I get in `From:` look like so: + +* `"updo: Junio C Hamano"` +* `"updo: Greg Kroah-Hartman"` +* `"updo: Eric Raymond: esr"` (article author != feed name, so we get both) +* `"updo: Jannis Pohlman: Jannis Pohlmann"` (oops! I tweaked the real updo) + +>>>> --[[schmonz]] + + +++ b/templates/rsspage.tmpl + + xmlns:atom="http://www.w3.org/2005/Atom" + +<atom:link href="<TMPL_VAR FEEDURL>" rel="self" type="application/rss+xml" /> + +Why is it using atom namespace inside an rss feed? What are the chances +every crummy rss reader on earth is going to understand this? I'd put it at +about 0%; I doubt ikiwiki's own rss reader understands such a mashup. +--[[Joey]] + +> The validator I used (<http://validator.w3.org/feed/>) told me to. +> Pretty sure it doesn't make anything work better in the podcatchers +> I tried. Hadn't considered that it might break some readers. +> Removed. --[[schmonz]] + + +<generator>ikiwiki</generator> + +Does this added tag provide any benefits? --[[Joey]] + +> Consistency with the Atom feed, and of course it trumpets ikiwiki +> to software and/or curious humans who inspect their feeds. The tag +> arrived only in RSS 2.0, but that's already the version we're +> claiming to be, and it's over a decade old. Seems much less risky +> than the atom namespace bits. --[[schmonz]] + +>> Sounds ok then. --[[Joey]] |