Use hex notation for entities
[atom.git] / README.org
1 atom.el -- An elisp library for creating Atom feeds
2
3 * Presentation
4
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.
10
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]]. 
13
14 * Installation
15
16 Put the file =atom.el= somewhere in your =load-path=, and add
17 =(require 'atom)= at the top of your Lisp program.
18
19 * First taste
20
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=.
24
25 A typical usage would look like this:
26
27 #+BEGIN_SRC elisp
28   (let ((my-atom-feed (atom-create "My feed" "http://example.org")))
29   
30     ;; A simple, text-only entry
31     (atom-add-text-entry
32      my-atom-feed
33      "Hello world"                        ; Title
34      "http://example.org/hello"           ; Permalink of the entry
35      "Hello the world!")                  ; Content of the entry
36   
37     ;; A text-only entry, with all the optional pieces of data
38     (atom-add-text-entry
39      my-atom-feed
40      "Bonjour"
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
50      "Bonjour, monde.")
51   
52     ;; an XHTML entry
53     (atom-add-xhtml-entry
54      my-atom-feed
55      "An XHTML example"
56      "http://example.org/html-example"
57      "<p>One can also use <acronym>XHTML</acronym> in the entries.</p>")
58   
59     ;; Get the resulting Atom feed (see also `atom-write-file')
60     (atom-print my-atom-feed))
61 #+END_SRC
62
63 See the docstrings for the methods above for more details.
64
65 * Additional notes
66
67 ** If what you want to do is not possible here
68
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:
74
75 #+BEGIN_SRC elisp
76   (let ((entry (atom-add-html-entry my-atom-feed
77                                     "Witty title"
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))))
84 #+END_SRC
85
86 ** Conformingness of produced feeds
87
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).
91
92 The encoding of the resulting feed is hard-coded to UTF-8.
93
94 ** Outputting RSS feeds
95
96 Use =atom-to-rss-print= and =atom-to-rss-write-file=.
97
98 Producing RSS from Atom feeds is not optimal. In particular :
99
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
102   the entry) ;
103
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
107   feeds.
108
109 ** XHTML entries
110
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=.
116
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=.
120
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:
123
124 #+BEGIN_SRC elisp
125   (atom-add-xhtml-entry
126     my-atom-feed
127     "An XHTML example"
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")))
134 #+END_SRC
135
136 This will save a call to =xml-parse-region=.
137
138 * License
139
140 =atom.el= -- An elisp library for creating Atom feeds.
141 Copyright (C) 2011 Frédéric Perrin.
142
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.
147
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.
152
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>