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"
  34      "http://example.org/hello"
  35      "Hello the world!")
  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 * Additionnal 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* ((content (assoc 'content entry))
  83            (attrs (xml-node-attributes entry)))
  84       (setcar (cdr entry) (cons '(lang . "en") attrs))))
  85 #+END_SRC
  86
  87 ** Conformingness of produced feeds
  88
  89 As of now, the library doesn't check whether there are two entries
  90 with the same =id= value (which is illegal), or with the same
  91 =updated= value (which reportedly confuse some readers).
  92
  93 The encoding of the resulting feed is hard-coded to UTF-8.
  94
  95 ** Outputting RSS feeds
  96
  97 Use =atom-to-rss-print= and =atom-to-rss-write-file=.
  98
  99 Producing RSS from Atom feeds is not optimal. In particular :
 100
 101 - the =updated= and the =pubDate= in the two standards don't seem to
 102   have the same semantics (last meaningfull change VS publication of
 103   the entry) ;
 104
 105 - the =description= of the channel is mandatory in RSS. The value for
 106   this element is taken from the =subtitle= element of an Atom feed,
 107   which is optional, so this library may produce non conforming RSS
 108   feeds.
 109
 110 ** XHTML entries
 111
 112 According to the w3c, relative links in an Atom feed can confuse feed
 113 readers. As a result, this library's default behaviour is to translate
 114 all addresses in the =href= attribute of =a= elements and =src= of
 115 =img= to absolute links. This can be disabled by setting NOCONVERT to
 116 t when calling =atom-add-xhtml-entry=.
 117
 118 In the =pre= element, whitespace is significant. However,
 119 =xml-parse-region= then =xml-print= will add spaces and
 120 identation. This is not something that can be fixed from =atom=.
 121
 122 If you already have ypur XHTML content in Lisp format (as opposed to
 123 simply a long string), you can pass it directly, as in:
 124
 125 #+BEGIN_SRC elisp
 126   (atom-add-xhtml-entry
 127     my-atom-feed
 128     "An XHTML example"
 129     "http://example.org/emacs-haiku"
 130     '((h1 nil "Emacs Haiku")
 131       (p nil "The friends chat gaily," (br)
 132          "I stand up to join their talk." (br)
 133          "My save-excursion." (br))
 134       (p ((class . "author-name")) nil "Oliver Scholz")))
 135 #+END_SRC
 136
 137 This will save a call to =xml-parse-region=.
 138
 139 * License
 140
 141 =atom.el= ---An elisp library for creating Atom feeds.
 142 Copyright (C) 2011 Frédéric Perrin.
 143
 144 This program is free software: you can redistribute it and/or modify
 145 it under the terms of the GNU General Public License as published by
 146 the Free Software Foundation, either version 3 of the License, or
 147 (at your option) any later version.
 148
 149 This program is distributed in the hope that it will be useful,
 150 but WITHOUT ANY WARRANTY; without even the implied warranty of
 151 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 152 GNU General Public License for more details.
 153
 154 The full text of the GNU General Public License can be found at the
 155 following address: <http://www.gnu.org/licenses/gpl-3.0.txt>