atom.el – An elisp library for creating Atom feeds

1. Presentation

This is a library for creating an Atom feed from a Lisp program. The normal usage is to create a feed with a title and a Web address. Once the feed has been created, entries may be added to the feed, by specifying (at the minimum) a title, a permanent link and the content of the entry. Text-only, HTML and XHTML entries are supported.

The code for this library is hosted at http://code.tar-jx.bz/atom.git; this manual can be found at http://tar-jx.bz/code/atom.html.

2. Installation

Put the file atom.el somewhere in your load-path, and add (require 'atom) at the top of your Lisp program.

3. First taste

The feed is created with atom-create, giving it a title and a Web address at the minimum. Entries may then be added one by one with atom-add-{text, html, xhtml}-entry.

A typical usage would look like this:

(let ((my-atom-feed (atom-create "My feed" "http://example.org")))

  ;; A simple, text-only entry
  (atom-add-text-entry
   my-atom-feed
   "Hello world"
   "http://example.org/hello"
   "Hello the world!")

  ;; A text-only entry, with all the optional pieces of data
  (atom-add-text-entry
   my-atom-feed
   "Bonjour"
   "http://example.org/bonjour"
   "Bonjour à tout le monde !"
   ;; optional: the last modification time
   (date-to-time "2011-01-30 23:40:12")
   ;; optional: an identifier for this entry; a common way to generate it is
   ;; to use the domain name and the creation date of the entry.
   (atom-generate-id "http://example.org"
                     (date-to-time "2011-01-30 10:01:05"))
   ;; optional: a summary for this entry
   "Bonjour, monde.")

  ;; an XHTML entry
  (atom-add-xhtml-entry
   my-atom-feed
   "An XHTML example"
   "http://example.org/html-example"
   "<p>One can also use <acronym>XHTML</acronym> in the entries.</p>")

  ;; Get the resulting Atom feed (see also `atom-write-file')
  (atom-print my-atom-feed))

See the docstrings for the methods above for more details.

4. Additionnal notes

4.1. If what you want to do is not possible here

The my-atom-feed object in the example above is really only an XML tree as defined by the xml.el package. This means you can manipulate it, as long as you are careful when manipulating the XML structure. For instance, if you want to add somebody as a contributor to an entry, and also add an lang attribute, you could say the following:

(let ((entry (atom-add-html-entry my-atom-feed
                                  "Witty title"
                                  "http://example.org/witty"
                                  "<p>This is <i>clever</i>, isn't it?")))
  (atom-modify-entry entry 'contributor
                     (atom-massage-author '("John Clever" "jc@example.net")))
  (let* ((content (assoc 'content entry))
         (attrs (xml-node-attributes entry)))
    (setcar (cdr entry) (cons '(lang . "en") attrs))))

4.2. Conformingness of produced feeds

As of now, the library doesn't check whether there are two entries with the same id value (which is illegal), or with the same updated value (which reportedly confuse some readers).

The encoding of the resulting feed is hard-coded to UTF-8.

4.3. Outputting RSS feeds

Use atom-to-rss-print and atom-to-rss-write-file.

Producing RSS from Atom feeds is not optimal. In particular :

  • the updated and the pubDate in the two standards don't seem to have the same semantics (last meaningfull change VS publication of the entry) ;
  • the description of the channel is mandatory in RSS. The value for this element is taken from the subtitle element of an Atom feed, which is optional, so this library may produce non conforming RSS feeds.

4.4. XHTML entries

According to the w3c, relative links in an Atom feed can confuse feed readers. As a result, this library's default behaviour is to translate all addresses in the href attribute of a elements and src of img to absolute links. This can be disabled by setting NOCONVERT to t when calling atom-add-xhtml-entry.

In the pre element, whitespace is significant. However, xml-parse-region then xml-print will add spaces and identation. This is not something that can be fixed from atom.

If you already have ypur XHTML content in Lisp format (as opposed to simply a long string), you can pass it directly, as in:

(atom-add-xhtml-entry
  my-atom-feed
  "An XHTML example"
  "http://example.org/emacs-haiku"
  '((h1 nil "Emacs Haiku")
    (p nil "The friends chat gaily," (br)
       "I stand up to join their talk." (br)
       "My save-excursion." (br))
    (p ((class . "author-name")) nil "Oliver Scholz")))

This will save a call to xml-parse-region.

5. License

atom.el —An elisp library for creating Atom feeds. Copyright (C) 2011 Frédéric Perrin.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The full text of the GNU General Public License can be found at the following address: http://www.gnu.org/licenses/gpl-3.0.txt

Auteur : Frédéric Perrin

Date : dimanche 6 février 2011

Sauf mention contraire, les textes de ce site sont sous licence Creative Common BY-SA.

Ce site est produit avec des logiciels libres 100% élevés au grain et en plein air.