From mboxrd@z Thu Jan 1 00:00:00 1970 From: "T.F. Torrey" Subject: Re: [ANN] Org to Atom, revisited Date: Tue, 15 Jun 2010 21:02:00 -0700 Message-ID: <4C184CB8.7080002@tftorrey.com> References: <87ocfcdyt3.wl%dmaus@ictsoc.de> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=58079 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OOjt5-0005fZ-LN for emacs-orgmode@gnu.org; Wed, 16 Jun 2010 00:06:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OOjt3-0002RZ-MA for emacs-orgmode@gnu.org; Wed, 16 Jun 2010 00:06:03 -0400 Received: from slow3-v.mail.gandi.net ([217.70.178.89]:34903) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OOjt3-0002Qm-E4 for emacs-orgmode@gnu.org; Wed, 16 Jun 2010 00:06:01 -0400 Received: from mrelay2-d.mgt.gandi.net (mrelay2-d.mgt.gandi.net [10.0.21.96]) by slow3-v.mail.gandi.net (Postfix) with ESMTP id C71F838C15 for ; Wed, 16 Jun 2010 06:02:23 +0200 (CEST) Received: from mfilter3-d.gandi.net (mfilter3-d.gandi.net [217.70.178.44]) by mrelay2-d.mgt.gandi.net (Postfix) with ESMTP id 646882251DE for ; Wed, 16 Jun 2010 06:02:13 +0200 (CEST) Received: from mrelay2-d.mgt.gandi.net ([10.0.21.96]) by mfilter3-d.gandi.net (mfilter3-d.gandi.net [217.70.178.44]) (amavisd-new, port 10024) with ESMTP id 4gaxLuK0nn9R for ; Wed, 16 Jun 2010 06:02:08 +0200 (CEST) Received: from [192.168.1.27] (ip98-165-69-201.ph.ph.cox.net [98.165.69.201]) (Authenticated sender: tftorrey@tftorrey.com) by mrelay2-d.mgt.gandi.net (Postfix) with ESMTPSA id A458C2251D5 for ; Wed, 16 Jun 2010 06:02:07 +0200 (CEST) In-Reply-To: <87ocfcdyt3.wl%dmaus@ictsoc.de> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org David, This is really great work, and I'm excited about using it for my own site. Hopefully this will be included in the official Org mode soon. Thank you for this. - Terry On 06/15/2010 09:51 AM, David Maus 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