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>