From: Amitai Schlair <schmonz-web-ikiwiki@schmonz.com>
Date: Wed, 20 Feb 2013 01:13:10 +0000 (-0500)
Subject: Document my fancypodcast WIP.
X-Git-Tag: 3.20130504~74^2~19
X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/commitdiff_plain/a31c2d4e0159902beddacb211c12ab2100797a3d?hp=3ab69aab06b1c2e19dd2ff808865662715f6e01b

Document my fancypodcast WIP.
---

diff --git a/doc/todo/fancypodcast.mdwn b/doc/todo/fancypodcast.mdwn
new file mode 100644
index 000000000..388df0e24
--- /dev/null
+++ b/doc/todo/fancypodcast.mdwn
@@ -0,0 +1,62 @@
+ikiwiki's simple podcasting, while elegant and minimal, doesn't (as
+mentioned in [[todo/blogging]]) produce full-featured feeds. In
+fancy podcasts, episodes are accompanied by text content. The feeds
+also have lots more metadata.
+
+[[!toc]]
+
+## 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
+
+[[!template id=gitbranch branch=schmonz/fancypodcast author="[[schmonz]]"]]
+
+### 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`.
+
+### Must-have (for [[schmonz]], anyway)
+
+* Write failing tests for the desired RSS/Atom behavior, then make
+  them pass, probably via changes to `{atom,rss}item.tmpl` and
+  [[plugins/inline]].
+* Enrich podcast feed metadata (some of which is iTunes-specific,
+  though I'm not aware of it causing any problems for other
+  podcatchers, and in fact some of them may also use it).
+* Subscribe to a fancy feed in some common podcatchers and compare
+  display details against a reference podcast.
+* Compare feature-for-feature and feed-for-feed with
+  [tru_podcast](http://www.rainskit.com/blog/542/tru_podcast-a-podcasting-plugin-for-textpattern),
+  which is what [[schmonz]] will be migrating from.
+* Think carefully about...
+    * UTF-8.
+    * Other templates with `CONTENT` and whether they want to learn
+      about `ENCLOSURE` (maybe `aggregatepost.tmpl`?).
+    * Whether [[tips/howto avoid flooding aggregators]] suffices for
+      migrating a fancy podcast into ikiwiki.
+* Verify that the feeds validate.
+* Verify that _all_ the tests pass (not just my new ones).
+
+### Nice-to-have
+
+* Let the enclosure's MIME type be specified, in case someone ever
+  needs to disagree with `File::MimeInfo`.
+* Extend [[plugins/inline]] to configurably generate additional
+  subscription links (such as iTunes) alongside the RSS/Atom ones.
+* Verify that [[plugins/more]] plays well with fancy podcasts.
diff --git a/doc/users/schmonz.mdwn b/doc/users/schmonz.mdwn
index fc7558b24..10ca6e6eb 100644
--- a/doc/users/schmonz.mdwn
+++ b/doc/users/schmonz.mdwn
@@ -2,7 +2,7 @@
 for all sorts of things. His attempts at contributing:
 
 [[!map
-pages="!*/Discussion and ((link(users/schmonz) and plugins/*) or rcs/cvs)"
+pages="!*/Discussion and ((link(users/schmonz) and plugins/*) or rcs/cvs or todo/fancypodcast)"
 ]]
 
 He's also written a plugin for [WIND