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.fperrin.net/atom.git.
  12
  13 * Installation
  14
  15 Put the file =atom.el= somewhere in your =load-path=, and add
  16 =(require 'atom)= at the top of your Lisp program.
  17
  18 * First taste
  19
  20 The feed is created with =atom-create=, giving it a title and a Web
  21 address at the minimum. Entries may then be added one by one with
  22 =atom-add-{text,html,xhtml}-entry=.
  23
  24 A typical usage would look like this:
  25
  26 #+BEGIN_SRC elisp
  27   (let ((my-atom-feed (atom-create "My feed" "http://example.org")))
  28
  29     ;; A simple, text-only entry
  30     (atom-add-text-entry
  31      my-atom-feed
  32      "Hello world"
  33      "http://example.org/hello"
  34      "Hello the world!")
  35
  36     ;; A text-only entry, with all the optional pieces of data
  37     (atom-add-text-entry
  38      my-atom-feed
  39      "Bonjour"
  40      "http://example.org/bonjour"
  41      "Bonjour à tout le monde !"
  42      ;; optional: the last modification time
  43      (date-to-time "2011-01-30 23:40:12")
  44      ;; optional: an identifier for this entry; a common way to generate it is
  45      ;; to use the domain name and the creation date of the entry.
  46      (atom-generate-id "http://example.org"
  47                        (date-to-time "2011-01-30 10:01:05"))
  48      ;; optional: a summary for this entry
  49      "Bonjour, monde.")
  50
  51     ;; an XHTML entry
  52     (atom-add-xhtml-entry
  53      my-atom-feed
  54      "An XHTML example"
  55      "http://example.org/html-example"
  56      "<p>One can also use <acronym>XHTML</acronym> in the entries.</p>")
  57
  58     ;; Get the resulting Atom feed (see also `atom-write-file')
  59     (atom-print my-atom-feed))
  60 #+END_SRC
  61
  62 * Additionnal notes
  63
  64 The =my-atom-feed= object in the example above is really only an XML
  65 tree as defined by the =xml.el= package. This means you can manipulate
  66 it, as long as you are careful not to mess up the XML structure. For
  67 instance, if you want to add somebody as a contributor to an entry,
  68 you could say the following:
  69
  70 #+BEGIN_SRC elisp
  71   (let ((entry (atom-add-html-entry my-atom-feed
  72                                     "Witty title"
  73                                     "http://example.org/witty"
  74                                     "<p>This is <i>clever</i>, isn't it?")))
  75     (atom-modify-entry entry 'contributor
  76                        (atom-massage-author '("John Clever" "jc@example.net"))))
  77 #+END_SRC
  78
  79 As of now, the library doesn't check whether there are two entries
  80 with the same =id= value (which is illegal), or with the same
  81 =updated= value (which reportedly confuse some readers).