1 atom.el -- An elisp library for creating Atom feeds
5 This is a library for creating an Atom feed from a Lisp program. The
6 normal usage is to create a feed with a title and a Web address. Once
7 the feed has been created, entries may be added to the feed, by
8 specifying (at the minimum) a title, a permanent link and the content
9 of the entry. Text-only, HTML and XHTML entries are supported.
11 The code for this library is hosted at [[http://code.tar-jx.bz/atom.git]];
12 this manual can be found at [[http://tar-jx.bz/code/atom.html]].
16 Put the file =atom.el= somewhere in your =load-path=, and add
17 =(require 'atom)= at the top of your Lisp program.
21 The feed is created with =atom-create=, giving it a title and a Web
22 address at the minimum. Entries may then be added one by one with
23 =atom-add-{text, html, xhtml}-entry=.
25 A typical usage would look like this:
28 (let ((my-atom-feed (atom-create "My feed" "http://example.org")))
30 ;; A simple, text-only entry
34 "http://example.org/hello" ; Permalink of the entry
35 "Hello the world!") ; Content of the entry
37 ;; A text-only entry, with all the optional pieces of data
41 "http://example.org/bonjour"
42 "Bonjour à tout le monde !"
43 ;; optional: the last modification time
44 (date-to-time "2011-01-30 23:40:12")
45 ;; optional: an identifier for this entry; a common way to generate it is
46 ;; to use the domain name and the creation date of the entry.
47 (atom-generate-id "http://example.org"
48 (date-to-time "2011-01-30 10:01:05"))
49 ;; optional: a summary for this entry
56 "http://example.org/html-example"
57 "<p>One can also use <acronym>XHTML</acronym> in the entries.</p>")
59 ;; Get the resulting Atom feed (see also `atom-write-file')
60 (atom-print my-atom-feed))
63 See the docstrings for the methods above for more details.
67 ** If what you want to do is not possible here
69 The =my-atom-feed= object in the example above is really only an XML
70 tree as defined by the =xml.el= package. This means you can manipulate
71 it, as long as you are careful when manipulating the XML structure. For
72 instance, if you want to add somebody as a contributor to an entry,
73 and also add an =lang= attribute, you could say the following:
76 (let ((entry (atom-add-html-entry my-atom-feed
78 "http://example.org/witty"
79 "<p>This is <i>clever</i>, isn't it?")))
80 (atom-modify-entry entry 'contributor
81 (atom-massage-author '("John Clever" "jc@example.net")))
82 (let* ((attrs (xml-node-attributes entry)))
83 (setcar (cdr entry) (cons '(lang . "en") attrs))))
86 ** Conformingness of produced feeds
88 As of now, the library doesn't check whether there are two entries
89 with the same =id= value (which is illegal), or with the same
90 =updated= value (which reportedly confuse some readers).
92 The encoding of the resulting feed is hard-coded to UTF-8.
94 ** Outputting RSS feeds
96 Use =atom-to-rss-print= and =atom-to-rss-write-file=.
98 Producing RSS from Atom feeds is not optimal. In particular :
100 - the =updated= and the =pubDate= in the two standards don't seem to
101 have the same semantics (last meaningfull change VS publication of
104 - the =description= of the channel is mandatory in RSS. The value for
105 this element is taken from the =subtitle= element of an Atom feed,
106 which is optional, so this library may produce non conforming RSS
111 According to the w3c, relative links in an Atom feed can confuse feed
112 readers. As a result, this library's default behaviour is to translate
113 all addresses in the =href= attribute of =a= elements and =src= of
114 =img= to absolute links. This can be disabled by setting NOCONVERT to
115 t when calling =atom-add-xhtml-entry=.
117 In the =pre= element, whitespace is significant. However,
118 =xml-parse-region= then =xml-print= will add spaces and
119 identation. This is not something that can be fixed from =atom.el=.
121 If you already have your XHTML content in Lisp format (as opposed to
122 simply a long string), you can pass it directly, as in:
125 (atom-add-xhtml-entry
128 "http://example.org/emacs-haiku"
129 '((h1 nil "Emacs Haiku")
130 (p nil "The friends chat gaily," (br)
131 "I stand up to join their talk." (br)
132 "My save-excursion." (br))
133 (p ((class . "author-name")) nil "Oliver Scholz")))
136 This will save a call to =xml-parse-region=.
140 =atom.el= -- An elisp library for creating Atom feeds.
141 Copyright (C) 2011 Frédéric Perrin.
143 This program is free software: you can redistribute it and/or modify
144 it under the terms of the GNU General Public License as published by
145 the Free Software Foundation, either version 3 of the License, or
146 (at your option) any later version.
148 This program is distributed in the hope that it will be useful,
149 but WITHOUT ANY WARRANTY; without even the implied warranty of
150 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
151 GNU General Public License for more details.
153 The full text of the GNU General Public License can be found at the
154 following address: <http://www.gnu.org/licenses/gpl-3.0.txt>