[Orgmode] Publish atom feeds based on Org files

[David Maus]

Hello all,

Carving another stone that might fit into the cathedral known as
Emacs/Orgmode I am glad to present attached file org-atom.el that
provides an exporting and a publishing function to create atom feeds
based on Org files.

To use org-atom.el you need the library atom-syndication.el, an
elisp implementation of the atom syndication format that can be found
in it's github repository.

http://github.com/dmj/atom-syndication/

Below you'll find a reduced ascii export of org-atom's project page
(currently at http://ictsoc.de/code/org-atom.html) that gives a brief
explanation of how to setup Org files for feed export.

Although both, atom-syndication.el and org-atom.el, are not quite
finshed yet, I decided to make the community aware of org-atom in the
hope some might try it out and give some feedback and ideas how to
extend org-atom's functionality.

My personal goal for org-atom is to make use of all functionality that
the atom syndication format provides: E.g. what popped into my mind is
that having an atom feed for Worg, especially the hacking-section
would be incredible.

Anyway: If you try org-atom and create feeds I'd like you to ask to
validate the feeds even if your feed reader accepts it.  Validating
the feed can be achived in two ways:

 - use the w3c feed validator at http://validator.w3.org/feed/

   It will not just validate the feed but also provide an short
   summary why a feed is not valid (if so) and suggestions on how to
   improve the feed.

 - use nxml-mode with the Relax NG Compact Syntax Grammar

   The syntax grammar is shipped with atom-syndication.el in the file
   atom-syndication.rnc.  Just open the feed file, maybe turn on nxml
   mode (M-x nxml-mode RET) and set the scheme file to
   atom-syndication.rnc (M-x rng-set-schema-file-and-validate RET
   /path/to/atom-syndication.rnc RET)

And here's the brief summary of the functions:

                Publish atom feeds based on Org files
                =====================================

Author: David Maus <address@hidden>
Date: 2010-03-19 22:23:01 CET


Table of Contents
=================
1 About
2 Exporting and publishing
    2.1 New infile export options
    2.2 Mapping of other Org entities to atom metadata elements
    2.3 Exporting a single Org file
    2.4 Publishing a feed for multiple files in a publishing project


1 About
~~~~~~~~

  This addon for Emacs Org mode, an Emacs Mode for Notes, Project
  Planning, and Authoring, provides export and publishing functions to
  create an atom feed based on Org files.

  This file provides some information on the concept, the state of
  implementation and a maybe some ideas how to extend the exporter.

2 Exporting and publishing
~~~~~~~~~~~~~~~~~~~~~~~~~~~

2.1 New infile export options
==============================

   =#+FEED_URL=: URL of the published feed.

                     This option MUST be present when exporting an Org
                     file using =org-export-as-atom=.

   =#+FEED_CONTENT_URL=: URL of the published html file.

        When exporting an Org file using =org-export-as-atom= and the
        customization variable =org-atom-publish-content= is not set,
        this option MUST be present.

   =#+FEED_ID=: Unique identifier of the feed.

                    If not set, the feed url is used as id.

   =#+FEED_MAP_ENTRIES=: A TAGS/PROP/TODO query that matches entry
        headlines.

        If not set, all headlines are exported as atom entries.

2.2 Mapping of other Org entities to atom metadata elements
============================================================

   In addition org-atom maps other Org mode entities to atom metadata
   elements.  Following table provides a comprehensive list of all
   currently supported metadata elements and their mapped Org
   entities.

2.2.1 atom:feed metadata
-------------------------

      Element                  Description                       Org entity
     
------------------------+---------------------------------+-------------------------------------
      atom:author name         name of author                    #+AUTHOR
      atom:generator name      name of generator                 const: 
`org-atom-generator-name'
      atom:generator version   version of generator              const: 
`org-atom-generator-version'
      atom:id                  unique id of feed                 #+FEED_ID
      atom:link rel="self"     link to the published feed        #+FEED_URL
      atom:updated             time when feed was updated        (current-time) 
on export
      atom:subtitle            subtitle or description of feed   #+DESCRIPTION
      atom:title               title of feed                     #+TITLE

2.2.2 atom:entry metadata
--------------------------

      Element                     Description                     Org entity
     
---------------------------+-------------------------------+---------------------------------------------
      atom:author name            name of author                  #+AUTHOR
      atom:content                content of feed entry           subtree of 
feed headline
      atom:id                     unique id of entry              ID property
      atom:link rel="alternate"   link to entry content           
#+FEED_CONTENT_URL
      atom:published              time when entry was published   property 
`org-atom-published-property-name'
      atom:title                  entry title                     headline 
title w/o TODO keywords and tags
      atom:updated                time when entry was updated     property 
`org-atom-updated-property-name'

2.3 Exporting a single Org file
================================

   A minimal setup of an Org file that will be published as atom feed
   could look like this:


,----
|   #+TITLE: Example file for feed export
|   #+AUTHOR: John Doe
|   #+EMAIL: address@hidden
|   #
|   #+FEED_URL: http://example.tld/~john/
|   #+FEED_CONTENT_URL: http://example.tld/~john/news.html
|   #+FEED_ID: a20d6ebc-7bab-4307-8b1c-7e29ac49bf66
|   #+FEED_MAP_ENTRIES: LEVEL=2
|   #
|
|   * This entry is not exported as feed
|
|   * Everything below this is!
|
|   ** Breaking news: Org now publishes atom feeds!
|      :PROPERTIES:
|      :ID:       ca13acc9-c14c-4707-b0e9-7f35687a4473
|      :Created:  [2010-03-19 Fr 15:55]
|      :END:
|
|   Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean
|   commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus
|   et magnis dis parturient montes, nascetur ridiculus mus. Donec quam
|   felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla
|   consequat massa quis enim. Donec pede justo, fringilla vel, aliquet
|   nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a,
|   venenatis vitae, justo. Nullam dictum felis eu pede mollis
|   pretium.
`----

   Calling =org-export-as-atom= on this file produces an atom feed:


,----
|   <feed xmlns="http://www.w3.org/2005/Atom";><title>Example file for feed 
export</title>
|   <generator version="0.1beta">Org/Atom</generator>
|   <id>urn:uuid:a20d6ebc-7bab-4307-8b1c-7e29ac49bf66</id>
|   <updated>2010-03-19T22:13:30+01:00</updated>
|   <link href="http://example.tld/~john/"; rel="self" />
|   <author><name>John Doe</name></author>
|   <entry><published>2010-03-19T15:55:00+01:00</published>
|   <content type="html">&lt;div id="outline-container-1" class="outline-3">
|   &lt;h3 id="sec-1">&lt;a name="ID-ca13acc9-c14c-4707-b0e9-7f35687a4473" 
id="ID-ca13acc9-c14c-4707-b0e9-7f35687a4473">&lt;/a>Breaking news: Org now 
publishes atom feeds! &lt;/h3>
|   &lt;div class="outline-text-3" id="text-1">
|
|
|   &lt;p>
|   Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean
|   commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus
|   et magnis dis parturient montes, nascetur ridiculus mus. Donec quam
|   felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla
|   consequat massa quis enim. Donec pede justo, fringilla vel, aliquet
|   nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a,
|   venenatis vitae, justo. Nullam dictum felis eu pede mollis
|   pretium.
|   &lt;/p>&lt;/div>
|   &lt;/div>
|   </content>
|   <link 
href="http://example.tld/~john/news.html#ca13acc9-c14c-4707-b0e9-7f35687a4473"; 
rel="alternate" />
|   <title type="html">
|   &lt;p>Breaking news: Org now publishes atom feeds!
|   &lt;/p></title>
|   <updated>2010-03-19T15:55:00+01:00</updated>
|   <id>urn:uuid:ca13acc9-c14c-4707-b0e9-7f35687a4473</id></entry></feed>
`----

2.4 Publishing a feed for multiple files in a publishing project
=================================================================

   To publish a feed for multiple Org files in a publishing project
   org-atom provides the function =org-atom-publish-feed-index= that
   can be plugged in a project's publishing alist as the
   =:index-function=:


,----
|   (setq org-publish-project-alist
|         '(
|           ...
|           ("news-feed"
|            :base-directory "~/website/"
|            :base-extension "org"
|            :publishing-directory "~/website/"
|            ;; new property :publishing-url
|            :publishing-url "http://example.tld/~john/";
|            :auto-index t
|            :index-filename "news.atom"
|            :index-title "News feed for address@hidden"
|            :index-function org-atom-publish-feed-index
|            ;; feed specific settings
|            :feed-id "6ea57592-69f2-4ef8-b44d-b7a511bd2fe8")
|           ...
|           ))
`----

   Please note the new publishing property =:publishing-url=: Instead
   of setting the feed url (=:feed-url=) in this alist and the content
   urls in each file =:publishing-url= is used to derive the url of
   the feed (assuming the feed is published under the same url) and
   the content url of the files.

   Running =org-publish= lets =org-atom-publish-feed-index= interate
   over all files in the project alist and create a combined feed for
   all entries of all processed files.

 -- David

--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... address@hidden
Email..... address@hidden

org-atom.el
Description: Binary data

pgpBfINkKH29K.pgp
Description: PGP signature