Fix nits

diff --git a/atom-tests.el b/atom-tests.el
index a725a55ac3d607f7bc9e5e04d9870a1a2a3a8218..941580a32d598f9e5b5bdc535f2a75155d5b9f1d 100644 (file)
--- a/atom-tests.el
+++ b/atom-tests.el
@@ -135,7 +135,7 @@
           :summary "<p>summary...</p>"))
 
     (atom-print my-atom-feed)
           :summary "<p>summary...</p>"))
 
     (atom-print my-atom-feed)

-    (atom-print-as-rss my-atom-feed)))
+    (atom-print-as-rss my-atom-feed "http://example.org/feed.rss")))

 
 (provide 'atom-tests)
 ;;; atom-tests.el ends here
 
 (provide 'atom-tests)
 ;;; atom-tests.el ends here

diff --git a/atom.el b/atom.el
index d0d2590bd23599556efa99cf5ca052fc46252c32..caca05c433b1c67121181794cf6c6ccc34c8c87a 100644 (file)
--- a/atom.el
+++ b/atom.el
@@ -50,7 +50,7 @@
 ;;   (atom-print-as-rss my-atom-feed))
 
 ;; Full documentation is available at <http://tar-jx.bz/code/atom.html>.
 ;;   (atom-print-as-rss my-atom-feed))
 
 ;; Full documentation is available at <http://tar-jx.bz/code/atom.html>.

-;; See 
+;; See atom-tests.el for usage examples.

 
 ;;; Code:
 
 
 ;;; Code:
 


@@ -71,14 +71,15 @@ PROPS is an optional plist with the following properties:
 - :subtitle is a subtitle for the feed; it can be a bit longer than
   TITLE, maybe a paragraph long.
 
 - :subtitle is a subtitle for the feed; it can be a bit longer than
   TITLE, maybe a paragraph long.
 

-- :self is the canonical URL to this feed.
+- :self is the canonical URL to this feed. If missing, the resulting
+  feed is non-conforming.

 
 - :id is a unique identifier for this feed. If not given, it
   defaults to :self.
 
 - :author is the author of the feed. See `atom-massage-author' for
 
 - :id is a unique identifier for this feed. If not given, it
   defaults to :self.
 
 - :author is the author of the feed. See `atom-massage-author' for

-the possible ways to specify it. In particular, `nil' uses
-`user-full-name' and `user-mail-address'.
+the possible ways to specify it. In particular, nil uses
+variable `user-full-name' and `user-mail-address'.

 
 - :updated is the date the feed was last updated. If not given,
 `(current-time)' is used."
 
 - :updated is the date the feed was last updated. If not given,
 `(current-time)' is used."


@@ -107,8 +108,9 @@ the possible ways to specify it. In particular, `nil' uses
     (nconc entry (list elem))))
 
 (defun atom-add-entry (atom title link content &optional props)
     (nconc entry (list elem))))
 
 (defun atom-add-entry (atom title link content &optional props)

-  "Add an entry to the atom flux ATOM. Return the newly added
-entry.
+  "Add an entry to the atom flux ATOM.
+
+Return the newly adde dentry.

 
 TITLE is a short, text-only, human readable string.
 
 
 TITLE is a short, text-only, human readable string.
 


@@ -118,15 +120,20 @@ may change between successive generations of the atom feed.
 CONTENT is the content of the entry; use `atom-add-html-entry'
 or `atom-add-xhtml-entry' when CONTENT is not text-only.
 
 CONTENT is the content of the entry; use `atom-add-html-entry'
 or `atom-add-xhtml-entry' when CONTENT is not text-only.
 

-If SUMMARY is not given, the entry will not contain any summary.
+PROPS is an optional plist with the following properties:
+
+- :summary, if is not given, the entry will not contain any summary.

 
 

-UPDATED defaults to `(current-time)' if omitted, which is
+- :updated defaults to `(current-time)' if omitted, which is

 probably not a very good default.
 
 probably not a very good default.
 

-ID defaults to LINK, which is not optimal; see `atom-generate-id'
-for a way to create good identifiers. For a given entry, it must
-not change between successive generations of the atom feed, even
-when the content of the entry changes."
+- :published, if given, is the earliest availability of the
+  entry. It is optional, and shouldn't change even if the entry
+  content (etc.) updated after the initial publication.
+
+- :id is a unique ID for the entry; defaulting to LINK. RFC4287
+  has specific requirements about valid IRI that may be used,
+  which this library does not try to enforce."

   (let ((entry (list (list 'title nil title))))
     (atom-modify-entry entry 'link  (list (list (cons 'href link))))
     (atom-modify-entry entry 'id (or (plist-get props :id) link))
   (let ((entry (list (list 'title nil title))))
     (atom-modify-entry entry 'link  (list (list (cons 'href link))))
     (atom-modify-entry entry 'id (or (plist-get props :id) link))


@@ -142,21 +149,27 @@ when the content of the entry changes."
 `atom-add-entry' for details.")
 
 (defun atom-add-html-entry (atom title link content &optional props)
 `atom-add-entry' for details.")
 
 (defun atom-add-html-entry (atom title link content &optional props)

-  "Add an entry to ATOM, with some HTML content. CONTENT should
-be a string enconding a valid HTML fragment. See `atom-add-entry'
-for additional details."
+  "Add an entry to ATOM, with some HTML content.
+
+TITLE, LINK, PROPS as in `atom-add-entry'. CONTENT should be a string
+enconding a valid HTML fragment. See `atom-add-entry' for
+additional details."

   (if (plist-member props :summary)
       (plist-put props :summary (atom-massage-html (plist-get props :summary))))
   (atom-add-entry atom title link (atom-massage-html content) props))
 
 (defun atom-add-xhtml-entry (atom title link content &optional props)
   (if (plist-member props :summary)
       (plist-put props :summary (atom-massage-html (plist-get props :summary))))
   (atom-add-entry atom title link (atom-massage-html content) props))
 
 (defun atom-add-xhtml-entry (atom title link content &optional props)

-  "Add an entry to ATOM, with some XHTML content. CONTENT may be
-given either as a string, or as an XML tree, of a valid XHTML
-fragment. See `atom-add-entry' for additional details."
+  "Add an entry to ATOM, with some XHTML content.
+
+TITLE, LINK, PROPS as in `atom-add-entry'. CONTENT may be given
+either as a string, or as an XML tree, of a valid XHTML fragment.
+See `atom-add-entry' for additional details."

   (if (plist-member props :summary)
       (plist-put props :summary (atom-massage-xhtml (plist-get props :summary))))
   (atom-add-entry atom title link (atom-massage-xhtml content) props))
 
   (if (plist-member props :summary)
       (plist-put props :summary (atom-massage-xhtml (plist-get props :summary))))
   (atom-add-entry atom title link (atom-massage-xhtml content) props))
 

+(defvar atom-xml-declaration "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n")
+

 (defun atom-print (atom)
   "Print the Atom feed ATOM in the current buffer."
   (insert atom-xml-declaration)
 (defun atom-print (atom)
   "Print the Atom feed ATOM in the current buffer."
   (insert atom-xml-declaration)


@@ -172,7 +185,9 @@ fragment. See `atom-add-entry' for additional details."
 
 \f
 (defun atom-to-rss (atom &optional rss-self)
 
 \f
 (defun atom-to-rss (atom &optional rss-self)

-  "Translate an Atom feed into an RSS one, returning the translation.
+  "Translate Atom feed ATOM into an RSS one, returning the translation.
+
+If RSS-SELF is given, it is used as self link of the RSS feed.

 
 Some information may be lost or approximated."
   (let ((rss (list (assoc 'title atom))))
 
 Some information may be lost or approximated."
   (let ((rss (list (assoc 'title atom))))


@@ -190,7 +205,7 @@ Some information may be lost or approximated."
     (reverse rss)))
 
 (defun atom-to-rss-item (entry)
     (reverse rss)))
 
 (defun atom-to-rss-item (entry)

-  "Translates an Atom entry into an RSS item."
+  "Translates the Atom entry ENTRY into an RSS item."

   (let ((item (list (assoc 'title entry))))
     (atom-to-rss-translator
      (xml-node-children entry) item
   (let ((item (list (assoc 'title entry))))
     (atom-to-rss-translator
      (xml-node-children entry) item


@@ -223,6 +238,9 @@ Some information may be lost or approximated."
       (setcdr (cdr link) (cons link-addr nil)))))
 
 (defun atom-print-as-rss (atom &optional rss-self)
       (setcdr (cdr link) (cons link-addr nil)))))
 
 (defun atom-print-as-rss (atom &optional rss-self)

+  "Convert Atom feed ATOM to RSS in the current buffer.
+
+If RSS-SELF is given, it is used as self link of the RSS feed."

   (let ((rss (atom-to-rss atom rss-self)))
     (insert atom-xml-declaration)
     ;; xmlns:atom included in order to allow the atom:link rel=self element
   (let ((rss (atom-to-rss atom rss-self)))
     (insert atom-xml-declaration)
     ;; xmlns:atom included in order to allow the atom:link rel=self element


@@ -233,8 +251,9 @@ Some information may be lost or approximated."
     (insert "</rss>")))
 
 (defun atom-to-rss-time (time)
     (insert "</rss>")))
 
 (defun atom-to-rss-time (time)

-  "Translates a string from the format used by Atom into the
-format used by RSS."
+  "Translate TIME from the format used by Atom into the format used by RSS.
+
+TIME is a string."

   (let ((system-time-locale "C"))
     (format-time-string "%a, %d %b %Y %T %z" (atom-parse-time time))))
 
   (let ((system-time-locale "C"))
     (format-time-string "%a, %d %b %Y %T %z" (atom-parse-time time))))
 


@@ -245,7 +264,9 @@ format used by RSS."
            (atom-to-rss-time (car (xml-node-children pubDate))))))
 
 (defun atom-to-rss-write-file (atom filename &optional rss-self)
            (atom-to-rss-time (car (xml-node-children pubDate))))))
 
 (defun atom-to-rss-write-file (atom filename &optional rss-self)

-  "Saves ATOM as a RSS feed into FILENAME."
+  "Save ATOM as a RSS feed into FILENAME.
+
+If RSS-SELF is given, it is used as self link of the RSS feed."

   (with-temp-buffer
     (atom-print-as-rss atom rss-self)
     (write-file filename)))
   (with-temp-buffer
     (atom-print-as-rss atom rss-self)
     (write-file filename)))


@@ -256,10 +277,8 @@ format used by RSS."
 
 (defvar atom-xhtml-namespace "http://www.w3.org/1999/xhtml")
 
 
 (defvar atom-xhtml-namespace "http://www.w3.org/1999/xhtml")
 

-(defvar atom-xml-declaration "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n")
-

 (defun atom-format-time (&optional time)
 (defun atom-format-time (&optional time)

-  "Format a time according to RFC3339."
+  "Format time value TIME according to RFC3339."

   ;; The time zone must be specified in numeric form, but with a colon between
   ;; the hour and minute parts.
   (replace-regexp-in-string
   ;; The time zone must be specified in numeric form, but with a colon between
   ;; the hour and minute parts.
   (replace-regexp-in-string


@@ -267,13 +286,15 @@ format used by RSS."
    (format-time-string atom-time-format-string time)))
 
 (defun atom-parse-time (&optional time)
    (format-time-string atom-time-format-string time)))
 
 (defun atom-parse-time (&optional time)

-  "Parse a time as specified in RFC3339 into Emacs's native format."
-  ;; Same remark as in `atom-format-time'
+  "Parse string TIME as specified in RFC3339 into Emacs's native format."
+  ;; Same remark as in `atom-format-time': RFC3339 wants a colon between hour
+  ;; and minute parts of the timezome, so remove it before `date-to-time'.

   (date-to-time (replace-regexp-in-string ":\\(..\\)$" "\\1" time)))
 
 (defun atom-massage-html (content)
   (date-to-time (replace-regexp-in-string ":\\(..\\)$" "\\1" time)))
 
 (defun atom-massage-html (content)

-  "Massage CONTENT so it can be used as an HTML fragment in an
-Atom feed. CONTENT must be a string."
+  "Massage CONTENT so it can be used as an HTML fragment in an Atom feed.
+
+CONTENT must be a string."

   (list '((type . "html")) content))
 
 (defun atom-string-to-xml (string)
   (list '((type . "html")) content))
 
 (defun atom-string-to-xml (string)


@@ -291,8 +312,7 @@ Atom feed. CONTENT must be a string."
       (car (xml-parse-region (point-min) (point-max))))))
 
 (defun atom-massage-xhtml (content)
       (car (xml-parse-region (point-min) (point-max))))))
 
 (defun atom-massage-xhtml (content)

-  "Massage CONTENT so it can be used as an XHTML fragment in an
-Atom feed."
+  "Massage CONTENT so it can be used as an XHTML fragment in an Atom feed."

   (list '((type . "xhtml"))
        (or (and (stringp content)
                 (atom-string-to-xml content))
   (list '((type . "xhtml"))
        (or (and (stringp content)
                 (atom-string-to-xml content))


@@ -300,8 +320,8 @@ Atom feed."
 
 (defun atom-massage-author (author)
   "Return an XML node representing the author. AUTHOR can be:
 
 (defun atom-massage-author (author)
   "Return an XML node representing the author. AUTHOR can be:

-- nil, in which case `user-full-name' and `user-mail-address' are
-  used;
+- nil, in which case variables `user-full-name' and `user-mail-address'
+  are used;

 - 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
 - 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


@@ -328,7 +348,7 @@ absolute, in the context of BASE, an URL."
 ;;; Functions that should probably not be there
 
 (defun url-canonalize (address base)
 ;;; Functions that should probably not be there
 
 (defun url-canonalize (address base)

-  "Make ADRESS an absolute URL, taking it in the BASE context."
+  "Make ADDRESS an absolute URL, taking it in the BASE context."

   ;; I feel such a function should exist in `url-parse'. Did I miss it?
   (let ((url-base (url-generic-parse-url base))
        (url-address (url-generic-parse-url address)))
   ;; I feel such a function should exist in `url-parse'. Did I miss it?
   (let ((url-base (url-generic-parse-url base))
        (url-address (url-generic-parse-url address)))


@@ -345,9 +365,5 @@ absolute, in the context of BASE, an URL."
     (xml-print (xml-node-children node))
     (buffer-string)))
 
     (xml-print (xml-node-children node))
     (buffer-string)))
 

-(defun xml-node-create (name attrlist childlist)
-  "Create a new XML node."
-  (list name attrlist . childlist))
-

 (provide 'atom)
 ;;; atom.el ends here
 (provide 'atom)
 ;;; atom.el ends here