From 19007bf94bfdd47e342e711b405ca196cc3bd681 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Fr=C3=A9d=C3=A9ric=20Perrin?= Date: Sat, 5 Feb 2011 10:30:09 +0100 Subject: [PATCH] Documentation. --- README.org | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++---- atom.el | 60 ++++++++++++++++++-------------------- 2 files changed, 106 insertions(+), 38 deletions(-) diff --git a/README.org b/README.org index e096a01..45e4611 100644 --- a/README.org +++ b/README.org @@ -8,7 +8,8 @@ the feed has been created, entries may be added to the feed, by specifying (at the minimum) a title, a permanent link and the content of the entry. Text-only, HTML and XHTML entries are supported. -The code for this library is hosted at http://code.fperrin.net/atom.git. +The code for this library is hosted at http://code.tar-jx.bz/atom.git; +this manual can be found at http://tar-jx.bz/code/atom.html. * Installation @@ -19,7 +20,7 @@ Put the file =atom.el= somewhere in your =load-path=, and add The feed is created with =atom-create=, giving it a title and a Web address at the minimum. Entries may then be added one by one with -=atom-add-{text,html,xhtml}-entry=. +=atom-add-{text, html, xhtml}-entry=. A typical usage would look like this: @@ -59,13 +60,17 @@ A typical usage would look like this: (atom-print my-atom-feed)) #+END_SRC +See the docstrings for the methods above for more details. + * Additionnal notes +** If what you want to do is not possible here + The =my-atom-feed= object in the example above is really only an XML tree as defined by the =xml.el= package. This means you can manipulate -it, as long as you are careful not to mess up the XML structure. For +it, as long as you are careful when manipulating the XML structure. For instance, if you want to add somebody as a contributor to an entry, -you could say the following: +and also add an =lang= attribute, you could say the following: #+BEGIN_SRC elisp (let ((entry (atom-add-html-entry my-atom-feed @@ -73,9 +78,78 @@ you could say the following: "http://example.org/witty" "

This is clever, isn't it?"))) (atom-modify-entry entry 'contributor - (atom-massage-author '("John Clever" "jc@example.net")))) + (atom-massage-author '("John Clever" "jc@example.net"))) + (let* ((content (assoc 'content entry)) + (attrs (xml-node-attributes entry))) + (setcar (cdr entry) (cons '(lang . "en") attrs)))) #+END_SRC +** Conformingness of produced feeds + As of now, the library doesn't check whether there are two entries with the same =id= value (which is illegal), or with the same =updated= value (which reportedly confuse some readers). + +The encoding of the resulting feed is hard-coded to UTF-8. + +** Outputting RSS feeds + +Use =atom-to-rss-print= and =atom-to-rss-write-file=. + +Producing RSS from Atom feeds is not optimal. In particular : + +- the =updated= and the =pubDate= in the two standards don't seem to + have the same semantics (last meaningfull change VS publication of + the entry) ; + +- the =description= of the channel is mandatory in RSS. The value for + this element is taken from the =subtitle= element of an Atom feed, + which is optional, so this library may produce non conforming RSS + feeds. + +** XHTML entries + +According to the w3c, relative links in an Atom feed can confuse feed +readers. As a result, this library's default behaviour is to translate +all addresses in the =href= attribute of =a= elements and =src= of +=img= to absolute links. This can be disabled by setting NOCONVERT to +t when calling =atom-add-xhtml-entry=. + +In the =pre= element, whitespace is significant. However, +=xml-parse-region= then =xml-print= will add spaces and +identation. This is not something that can be fixed from =atom=. + +If you already have ypur XHTML content in Lisp format (as opposed to +simply a long string), you can pass it directly, as in: + +#+BEGIN_SRC elisp + (atom-add-xhtml-entry + my-atom-feed + "An XHTML example" + "http://example.org/emacs-haiku" + '((h1 nil "Emacs Haiku") + (p nil "The friends chat gaily," (br) + "I stand up to join their talk." (br) + "My save-excursion." (br)) + (p ((class . "author-name")) nil "Oliver Scholz"))) +#+END_SRC + +This will save a call to =xml-parse-region=. + +* License + +=atom.el= ---An elisp library for creating Atom feeds. +Copyright (C) 2011 Frédéric Perrin. + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +The full text of the GNU General Public License can be found at the +following address: diff --git a/atom.el b/atom.el index 5d3df7b..693c606 100644 --- a/atom.el +++ b/atom.el @@ -27,8 +27,7 @@ ;; permanent link and the content of the entry. Text-only, HTML and ;; XHTML entries are supported. -;; A feed is really a Lisp structure as used by the `xml.el' package, -;; without the parent `feed' element. +;; It is possible to produce both Atom and RSS feeds. ;; A typical usage would look like this: @@ -40,27 +39,17 @@ ;; "http://example.org/hello" ;; "Hello the world!") ;; -;; ; A text-only entry, with all the optional pieces of data -;; (atom-add-text-entry -;; my-atom-feed -;; "Bonjour" -;; "http://example.org/bonjour" -;; "Bonjour à tout le monde !" -;; ;; optional: the last modification time -;; (date-to-time "2011-01-30 23:40:12") -;; ;; optional: an identifier for this entry; a common way to generate it is -;; ;; to use the domain name and the creation date of the entry. -;; (atom-generate-id "http://example.org" -;; (date-to-time "2011-01-30 10:01:05")) -;; ;; optional: a summary for this entry -;; "Bonjour, monde.") -;; ;; (atom-add-xhtml-entry ;; my-atom-feed ;; "An XHTML example" ;; "http://example.org/html-example" ;; "

One can also use XHTML in the entries.

") -;; (atom-print my-atom-feed)) +;; +;; (atom-print my-atom-feed) +;; ;; If you prefer RSS feeds: +;; (atom-to-rss-print my-atom-feed)) + +;; Full documentation is available at . ;;; Code: @@ -214,7 +203,7 @@ Some information may be lost or approximated." (setcar (cdr guid) (list (cons 'isPermaLink "false")))) (if (and descr (equal (xml-get-attribute descr 'type) "xhtml")) - (setcar (cddr descr) (xml-node-text descr)))) + (setcar (cddr descr) (xml-node-as-text descr)))) `(item nil ,@item))) (defun atom-to-rss-translator (source target translations) @@ -225,11 +214,6 @@ Some information may be lost or approximated." (when data (atom-modify-entry target to data))))) -(defun xml-node-text (node) - (with-temp-buffer - (xml-print (xml-node-children node)) - (buffer-string))) - (defun atom-to-rss-modify-link (entry) (let* ((link (assoc 'link entry)) (link-addr (xml-get-attribute-or-nil link 'href))) @@ -306,7 +290,8 @@ Atom feed." "Return an XML node representing the author. AUTHOR can be: - nil, in which case `user-full-name' and `user-mail-address' are used; -- a single string, the full name of the author; +- a single string, the full name of the author; no email address + will be included; - a list with two elements, the full name and the email address of the author; - something else, assumed to be a complete `atomPersonConstruct'." @@ -327,6 +312,18 @@ absolute, in the context of BASE, an URL." (dolist (child (xml-node-children node)) (when (listp child) (atom-xhtml-convert-links child base)))) +(defun atom-generate-id (link creation-date) + "Generate a string suitable for use as an atom:id element. This +implements Mark Pilgrom's tag: URI method, using the +CREATION-DATE of the entry, and the domain part of LINK." + (format "tag:%s,%s:/%s" + (url-host (url-generic-parse-url link)) + (format-time-string "%Y-%m-%d" creation-date) + (format-time-string "%Y%m%d%H%M%S" creation-date))) + + +;;; Functions that should probably not be there + (defun url-canonalize (address base) "Make ADRESS an absolute URL, taking it in the BASE context." ;; I feel such a function should exist in `url-parse'. Did I miss it? @@ -339,14 +336,11 @@ absolute, in the context of BASE, an URL." (file-name-directory (url-filename url-base)))) (url-recreate-url url-base)))) -(defun atom-generate-id (link creation-date) - "Generate a string suitable for use as an atom:id element. This -implements Mark Pilgrom's tag: URI method, using the -CREATION-DATE of the entry, and the domain part of LINK." - (format "tag:%s,%s:/%s" - (url-host (url-generic-parse-url link)) - (format-time-string "%Y-%m-%d" creation-date) - (format-time-string "%Y%m%d%H%M%S" creation-date))) +(defun xml-node-as-text (node) + "Return a string representing NODEn, an XML structure." + (with-temp-buffer + (xml-print (xml-node-children node)) + (buffer-string))) (provide 'atom) ;;; atom.el ends here -- 2.43.0