RSS Feeds

[igbanam]

Thanks for putting this together ❣️

I am interested in vending an RSS feed for this site. With an RSS feed, digests can be delivered into readers' feeds whenever a new paper is posted. The one thing this hurts is site-visit metrics; if at all tracked. I believe though that the utility of rubybib.org is to vend scientific papers around Ruby. So making this data widely available may be beneficial. As an effort towards a machine-readable format, this is related to #17

Currently, the details of these papers are collected in index.md. This then renders through the layout and …we have a website! While this works — and works quite neatly, if you ask me — it can be better. "better" here would change the site a bit to allow it vend the data in other formats. What I am thinking about is the change below

CURRENT

+----------------+
|    index.md    |
|                |       +-----HTML------+
|  +-----------+ >------->  rubybib.org  |
|  | Site Data | |       +---------------+
|  +-----------+ |
+----------------+

PROPOSED

                               +-------rubybib.org---------+
                               |                           |
                               |      +----------+         |
                               |  +---> RSS Feed |         |
                               |  |   +----------+         |
                               |  |                        |
+-----------+    +----------+  |  |   +-----------+        |
| Site Data >----> Renderer >--|--+---> HTML Site |        |
+-----------+    +----------+  |  |   +-----------+        |
                               |  |                        |
                               |  |   +------------------+ |
                               |  +---> ...other formats | |
                               |      +------------------+ |
                               |                           |
                               +---------------------------+

There are a few ways I have thought about getting this done

1. Harness Jekyll
2. Custom rendering as build step 👈🏾  I prefer this
3. Manual RSS

Harness Jekyll

Github Pages is currently built on Jekyll. Jekyll can be used to generate a static blog site. Posts from the generated blog can be vended as RSS using the jekyll-feed plugin.

This option requires we change the format of the site to list each entry as a blog post. The list of entries can be displayed on the homepage as currently is. The actual blog page itself would display the same information — this is redundant — unless there is extra information which comes with a paper.

Pros

• We get the feed for free if the site follows the Jekyll standard
• RubyBib could expand to "thoughts on paper" — if ever needed — with the posts section

Cons

• TTM — Site redesign may be too much an ask for an RSS feed
• A change costs more in terms of artefacts, and build process
• Data is broken into many "posts"

Custom Render Build-Step

If we decouple the data from index.md, we could create a render step which generates an index.md, and an rss.xml — or whatever we choose to call it — and inject this render step before the Jekyll build step. The data currently housed in index.md would now be housed in a single flat file; I'm thinking JSON or YAML, whichever appeals the most to RubyBib. Adding papers to the collection — judging from some commits: for "Add RbSyn", for "RubyComp" and for "Jcll branch for RubyRTL reference" — could now simply be an entry into the flat data file.

Pros

• Small change
• Small change to change process (machine cost)
• Single location for all papers data

Cons

• Slight increase in release flow; extra render step

Manual RSS

In the end, the solution to this issue is an RSS feed. We could hand-write an RSS feed and keep this updated whenever we add papers to RubyBib.

Pros

• Quickest TTM

Cons

• Initial time capital required to transform papers data to RSS
• Needs extra pull-request process to keep in sync with papers data
• Equivalent change to change process (human cost)

[igbanam]

Now I post this up, I see a better way to digest the options in the context of the proposed solution.

1. The renderer is jekyll-feed
2. The renderer is a custom script + a workflow step
3. The renderer is a human

[chrisseaton]

Thanks for your comprehensive thoughts. I think I prefer

flowchart LR
    index.yaml --> index.md
    index.yaml --> index.rss

Loading

done statically, and all three checked-in. Not a huge fan of the idea of a complex Jekyll setup.

Here's a question - does the RSS feed list papers when they're added, or when published? So if I add an old paper does it fit into the feed when it was published, and would that cause people to miss it? Or is the feed a kind of change-log? I don't use RSS.

[chrisseaton]

And possibly index.yaml should really be index.bib? But then the problem is, like the original issue, this laborious work to convert to BibTeX (it's a fiddly format.) I guess we could do index.yaml first and index.bib later though.

[igbanam]

Cool image! — this is similar to the second option; the one I prefer. Only difference is we'd only be worried about checking in index.yaml; the rest would be handled by workflows (Github Actions) and pages publishing during deploy time. Github Pages deploys the _site folder; the output of jekyll build. I just did a small check and yes, this is possible. If there's an XML file in the home directory prebuild, building the site copies that file into the build folder.

Addressing the question on ordering items in the RSS feed… the feed belongs to RubyBib. So it should list files as you add them; i.e. current reverse commit order. We can tag on the current date as the "addition date" in index.yaml. We can then use that to generate a feed.

Question: I see the papers have categories. What are their current orderings within a category?

I don't know the .bib format. I agree we can go with .yaml for now. When someone who knows the BibTeX specs comes along, we can make that transition.

[chrisseaton]

Are you intending to work on an implementation? Or were you just proposing the idea? Please engage with me early while you develop.

[igbanam]

Oh I consider myself as owner and spearhead of this request. So I intend to build this. It's small enough to handle alone. But I don't want to begin until we agree on what should be done. That's why the plenty conversation beforehand