The Org to Atom exporter I've preliminary announce some weeks ago
entered a state I consider to be stable and consistent enough to be
included into Org mode.
It provides export, publishing and a sitemap functions that let you
create an Atom feed for a web page project based on (multiple) Org
mode files. An example that shows the support of inline images in
feed entry content can be found [here].
[here]: http://ictsoc.de/code/org-atom/example.atom
* Download and installation
The Org to Atom exporter is maintained in a copy of Org mode's git
repository in branch "org-atom" located at
git://github.com/dmj/dmj-org-mode.git
You can download the most recent version at
[http://github.com/dmj/dmj-org-mode/raw/org-atom/lisp/org-atom.el]
To use the exporter you need a recent version of atom-syndication.el,
an elisp implementation of the Atom Syndication Format. You can get
atom-syndication.el from github, too:
git://github.com/dmj/atom-syndication.git
* Usage
Please see the almost complete documentation below or read via web at
[http://ictsoc.de/code/org-atom.html]
* Backward incompatibility
If you have used an older version of the exporter you need to revise
your configuration due to incompatible changes. Most notably:
- in-buffer options and publishing properties have be (re)renamed
to start with #+FEED and :feed instead of #+ATOM and :atom;
- support for the atom:category element is temporarily removed;
- some default values have changed:
- content is not published by default
- names of the atom:updated and atom:published property default to
atom_updated and atom_published
* Things yet to be done
Besides support of even more atom elements (e.g. use tags for the
atom:category element), the exporter would require a proper
documentation for the Org mode manual, and of course some real-world
testing. Thus I'm interested not just in bugs, glitches,
inconsistencies, and complains about the exporter but some feedback
about the present documentation, too.
* Documentation
Publish Atom feeds based on Org files
=====================================
Date: 2010-06-15 18:49:21 CEST
Table of Contents
=================
1 Exporting an Org file to Atom
1.1 In-buffer options
1.2 Headline properties
1.3 Export settings
1.4 Example
2 Publish feeds for a web page project
2.1 Publish a feed for each file in the project
2.2 Publish a combined feed for project files
1 Exporting an Org file to Atom
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An Atom feed consists of a head with feed meta data (e.g. feed title
and description) and one or more feed entries. The exporter maps Org
mode subtrees to Atom feed entries and requires special in-buffer
options with feed as well as headline properties with entry specific
meta data.
1.1 In-buffer options
======================
An Atom feed is identified by a globally unique identifier, preferably
a UUID. Such an identifier must be present in a Org file supposed to
get exported or published to Atom in the =#+FEED_ID= in-buffer option.
If you do not use a UUID, the value of this in-buffer option must be a
proper IRI, like for example a URL that identifies this particular
feed.
To be able to properly reference feed entry content and the feed
itself[1], at least the URL of the feed must be given
by the =#+FEED_URL=. By default Org assumes the published content
available in the same place like the feed with the name of the Org
file and the extension defined in =org-export-html-extension=.
For example a feed for the file =example.org= with the in-buffer
option =#+FEED_URL= set to =http://example.tld/feed.atom= is expected
to reference content located on the URL
=http://example.tld/example.html=.
If you indent to use different URLs for the feed and the referenced
content, you can set the content URL manually by providing the
in-buffer option =#+FEED_CONTENT_URL=.
Prospective feed entries are found by using the TAGS/PROP/TODO query
specified in the =#+FEED_MAP_ENTRIES= option.
If present, the exporter uses the in-buffer options =#+TITLE= and
=#+DESCRIPTION= for the feed title and description. If no title is
given, the exporter uses the file name. If you want the feed title or
description to be different than title and description of the
published HTML file, you can use the in-buffer options =#+FEED_TITLE=
and =#+FEED_DESCRIPTION=.
Atom feeds are required to have an associated author of a feed and its
entries. Exporting an Org file to Atom thus always uses the author
specified with the =#+AUTHOR= option as the name of the author of a
feed. If this option is not present, Org falls back to use whatever
the variable =user-full-name= is set to.
1.2 Headline properties
========================
A headline that matches the TAGS/PROP/TODO query for feed entries
requires at least two headline properties to be present: The =ID=
property with a unique identifier of the headline (preferable a UUID)
and a property called =atom_published= containing a time stamp with
the date an entry should be considered to be published. If these two
properties are not present, they are automatically created using Org's
default method to create ID properties[2] and current time and date for the
publishing
date[3]
By default Org just publishes a link to the content of feed entry
headlines. If you set the customization variable
=org-atom-publish-content=, the whole subtree of a feed entry headline
will be published within the feed entry.
If you want the Atom entry point to a location different than the
published HTML file, you can put the URL in the property
=atom_href_alternate=. Additionally you can reference URLs related to
the Atom entry by putting them into the property =atom_href_related=
and a possible source of the information present in the headline in
the property =atom_href_via=.
1.3 Export settings
====================
The =#+FEED_OPTIONS= line is a compact1 form to specify export
settings. Here you can:
git: turn on/off usage of =git blame= to obtain headline creation date
content: turn on/off publishing content
1.4 Example
============
#+TITLE: News about example.tld
#+AUTHOR: John Doe
#+FEED_ID: f6c537d7-6733-427b-a2d5-a6a14b81a967
#+FEED_URL: http://example.tld/news.atom
#+FEED_CONTENT_URL: http://example.tld/news.html
#+FEED_MAP_ENTRIES: LEVEL=2+feed
Calling =org-export-as-atom= on a file containing these in-buffer
options will create an Atom feed with the title "News about
example.tld" by the author "John Doe" and all level 2 headlines with
the tag "feed" as feed entries.
2 Publish feeds for a web page project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Atom exporter provides a publishing and a sitemap function to
create Atom feeds in a publishing project. While the publishing
function creates a feed for each file in the project that contains at
least one feed entry headline, the sitemap function combines feed
entries of the project files into one single feed.
2.1 Publish a feed for each file in the project
================================================
The function =org-publish-org-to-atom= can be used to create an Atom
feed for every file in a publishing project that contains at least one
feed entry headline. Files that do not contain feed entry headlines
either because =#+FEED_MAP_ENTRIES= does not match or is not present
are silently skipped.
If the publishing project property =:publishing-url= is set and a file
contains feed entries but no =#+FEED_URL= or =#+FEED_CONTENT_URL=
in-buffer option, the URLs are automatically derived from this
property assuming the files in =:publishing-directory= are published
relative to this URL.
If the published files have an extension other than "html" you can
specify the content file extension by the property
=:feed-content-extension=.
2.2 Publish a combined feed for project files
==============================================
For publishing a combined feed for all entries in a project Org
provides a sitemap function =org-atom-publish-org-as-atom-index=. It
iterates over all files in the project, collects prospective feed
entries and creates a combined feed in the file specified by
=:sitemap-file=.
Obviously feed metadata must be supplied in the publishing project:
The property =:feed-id= holds the unique identifier for the feed,
=:feed-title= the feed's title, and =:publishing-url= the base URL of
the published project. I.e. the feed and its entry's content in
=:base-directory= are assumed to be relative to this URL.
Footnotes:
[1] The specifications highly recommend a feed referencing its
own location on the web.
[2] See customization variable
=org-id-method=
[3] If you maintain your files in a git repository, you might
look at the customization variable
=org-atom-try-prepare-headline-git=. If it is non-nil, Org tries to
obtain a date for a headline using the =git blame= command.
_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
address@hidden
http://lists.gnu.org/mailman/listinfo/emacs-orgmode