David, I love the idea of this project, and I really hope it makes it into org proper!
Unfortunately I haven't been able to get the sitemap/index feed feature in this or an older version to work for me. Can you add more details in Section 4.2? It mentions org-atom-publish-org-as-atom-index but it's not in http://github.com/dmj/dmj-org-mode/raw/org-atom/lisp/org-atom.el. In the old version I think you had to put something like this the project-alist :index-function org-atom-publish-feed-index Is that still necessary? What about :auto-index t? Maybe explain how to publish the sitemap? Does it just happen when you publish the project? Maybe an example? TIA Scott On Tue, Jun 15, 2010 at 10:51 AM, David Maus <dm...@ictsoc.de> wrote: > > 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. > Emacs-orgmode@gnu.org > http://lists.gnu.org/mailman/listinfo/emacs-orgmode > _______________________________________________ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode
