Re: resource_feeder feedback

Hi Sam, thanks for the feedback!  Comments below...

On 9/26/06, Sam Ruby <rubys@xxxxxxxxxxxxxxxx> wrote:
>
> Let me apologize in advance as this is a topic that I feel passionate
> and opinionated about.  If I'm coming on too strong, please forgive me.
>
> === Be opinionated===
>
> My first piece of advice is simple: be opinionated.  Change the method
> name to simply <feed_for>.  Have it default to doing the right thing.
> Perhaps give an option to change the default feed format, but default to
> providing only a single feed format.  That's what Microsoft [1],
> FeedDemon [2], Bloglines [3] and many others would prefer.

I like this idea.  I tend to think of Atom as the correct feed format
to use, but I don't know if anyone else will agree.

>
> === Summary and Content ===
>
> Independent of feed format, my biggest input is that you think a bit
> more about description.  It has a number of problems.  The first can be
> expressed thus: undoubtedly the column in the database from which this
> element is often sourced is of some string type; in such cases: what
> would a '<' character in such a column mean?  Does it signal the start
> of markup?  Or is it simply a less than character?
>
> My experience is that most string columns in a database are simply plain
> text.  That also tends to be the 'safe' choice in most cases; treating
> markup as plain text will expose the markup.  This , while suboptimal,
> at least is obvious.  In the reverse case, what you have is silent data
> loss [6].
>
> [6] http://www.intertwingly.net/blog/2004/05/28/detente
>
> If you want to put plain text in an RSS 1.0 or RSS 2.0 <description>,
> and you are using Builder 2.0 (you *are* using Builder 2.0, aren't
> you?), then you need to add a .to_xs to escape the string.  If you want
> to put plain text into an Atom <summary> or <content element>, you need
> do nothing as that is the default.
>
> Now you need a convention (possibly as simple as
> .downcase.ends_with?("html")) and an a way to override this (perhaps
> options[:feed][:content_type]?).  If content_type=='html', you want to
> omit the call to .to_xs for RSS 1.0 and RSS 2.0.  For Atom, simply do
>
>    xml.content(:type => options[:feed][:content_type] || ... || 'text')

I think this is a good idea.  I had a feeling I'd be revisiting this
part as I wrote the initial version.

> Next, consider internationalization / character encoding issues.
> Builder prefers utf-8; but with Builder 2.0 it will fall back to
> iso-8859-1/win-1252.  This is the right default for a wide number of
> cases, but it will be wrong in a case that you might care about: native
> Mac applications.
>
> Finally, consider splitting summary and content.  Summary should go into
> description in RSS 1.0 and RSS 2.0; but content should go into
> content:encoded.  This extension enjoys wide support, so it is safe to
> use [7]. For Atom, summary and content go into summary and content
> respectively.  Additionally, with Atom, you can put XML directly into
> the content; this may be a reasonable default.
>
> [7] http://www.rssboard.org/rss-profile#namespace-elements-content-encoded

I thought about doing that too.  I just wasn't really sure how to
handle that cleanly.  I wasn't sure if most resources would have a
summary field or not.   Perhaps they would if you're providing a feed
for it however.

> === Other details ===
>
> You declare xmlns:dc; you really want to use this.  Put some author
> information into the feed [8].  This goes for all feed versions, though
> Atom structures this information differently.  Author information can
> either be a single author for the entire feed, or an author for each
> entry, or both.
>
> [8] http://www.rssboard.org/rss-profile#namespace-elements-dublin-creator
>
> The default feed title probably should include the database name.
>
> You omit channel description if there isn't an options which specify
> this value; doing this is only valid in Atom 1.0; with RSS 1.0 and RSS
> 2.0 channel description is required.

Should I just leave it blank for RSS?  I figured it was up to the
developer to provide a description if they wanted valid RSS.

> Omitting language if it isn't specified is probably better than
> defaulting to en-us.

If that's the best practice, that's cool.

> Re: TTL, before you go there, read [9].
>
> [9] http://www.rssboard.org/rss-profile#element-channel-ttl
>
> Entry/Item titles have much the same problems as descriptions in RSS
> 2.0, only there isn't nearly as much consensus on how to escape it.  In
> particular, in generally it isn't possible find a representation that
> allows you to express a '<' character in a title.  This problem doesn't
> exist in Atom 1.0.
>
> Overall on the nomenclature: be consistent.  You currently have
> options[:feed][:item].  This should either be options[:channel][:item]
> (matching RSS) or options[:feed][:entry] (matching Atom).

I'm in favor of matching Atom terminology, since the current
restful/resource stuff was heavily inspired by it.

> === PDI ===
>
> Since PDI is potentially the response that this post deserves, let me
> point out that resource_feeder doesn't really require much code to
> implement.  :-)
>

We accept patches :)  Since implementing this on a small side project,
I've been rethinking the approach a bit.  I'm wondering if a little
DSL would work better?

Example:

# simple
format.atom { render_feed_for(@rumors) }

# actual usage in my app
format.atom do
  render_atom_feed_for(@rumors, {
    :feed => { :title => 'Upcoming Rumors | is it fake or not?',
      :description => 'Upcoming rumors on isitfakeornot.com',
      :link => upcoming_rumors_url },
    :item => { :description => :body,
      :title => lambda { |r| "#{r.title} by #{r.user.login}"} }
    }
  )
end

# to
format.atom { render :action => 'index.rfeed' }

# index.rfeed

feed_for @rumors, :format => :rss do |f|
  f.title 'Upcoming Rumors | is it fake or not?'
  f.description 'Upcoming rumors on isitfakeornot.com'
  f.link upcoming_rumors_url
  f.time_to_live 45

  f.entry do |e|
    e.title do |resource|
      "#{resource.title} by #{resource.user.login}"
    end

    e.description :body, :content_type => :html
  end
end

I think the expanded DSL will look better, especially once you start
adding options for summaries, authors, etc.  Also, since it's rendered
with ActionView, it has access to any helpers that you don't have in
the controller.

Now, I just need to write this because I really want it in Mephisto...

-- 
Rick Olson
http://weblog.techno-weenie.net
http://mephistoblog.com

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Ruby 
on Rails: Core" group.
To post to this group, send email to rubyonrails-core@xxxxxxxxxxxxxxxx
To unsubscribe from this group, send email to 
rubyonrails-core-unsubscribe@xxxxxxxxxxxxxxxx
For more options, visit this group at 
http://groups.google.com/group/rubyonrails-core
-~----------~----~----~----~------~----~------~--~---