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: #+BEGIN_SRC elisp (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" "

One can also use XHTML in the entries.

") ;; Get the resulting Atom feed (see also `atom-write-file') (atom-print my-atom-feed)) #+END_SRC 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: #+BEGIN_SRC elisp (let ((entry (atom-add-html-entry my-atom-feed "Witty title" "http://example.org/witty" "

This is clever, 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)))) #+END_SRC ** 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: #+BEGIN_SRC elisp (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"))) #+END_SRC 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: