Skip to content
atom.el -- An elisp library for creating Atom feeds
Emacs Lisp
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
README.org
atom.el
xml-xhtml-entities.el

README.org

atom.el – An elisp library for creating Atom feeds

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.

Installation

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

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"                        ; Title
   "http://example.org/hello"           ; Permalink of the entry
   "Hello the world!")                  ; Content of the entry

  ;; 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.

Additional notes

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* ((attrs (xml-node-attributes entry)))
    (setcar (cdr entry) (cons '(lang . "en") attrs))))

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.

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.

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.el.

If you already have your 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.

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

You can’t perform that action at this time.