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: