From mboxrd@z Thu Jan 1 00:00:00 1970 From: Scott Jaderholm Subject: Re: [ANN] Org to Atom, revisited Date: Tue, 6 Jul 2010 23:38:01 -0600 Message-ID: References: <87ocfcdyt3.wl%dmaus@ictsoc.de> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Return-path: Received: from [140.186.70.92] (port=45869 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OWNL1-0001jr-0r for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 01:38:28 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OWNKx-0008Qa-9P for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 01:38:26 -0400 Received: from mail-pw0-f41.google.com ([209.85.160.41]:55589) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OWNKx-0008QJ-0S for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 01:38:23 -0400 Received: by pwi8 with SMTP id 8so1782293pwi.0 for ; Tue, 06 Jul 2010 22:38:21 -0700 (PDT) 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: David Maus Cc: org-mode David, I love the idea of this project, and I really hope it makes it into org pro= per! 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-a= list =A0=A0=A0=A0=A0=A0=A0=A0=A0=A0=A0 :index-function org-atom-publish-feed-ind= ex 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 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. =A0An 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 > > =A0The Org to Atom exporter is maintained in a copy of Org mode's git > =A0repository in branch "org-atom" located at > > =A0git://github.com/dmj/dmj-org-mode.git > > =A0You can download the most recent version at > > =A0[http://github.com/dmj/dmj-org-mode/raw/org-atom/lisp/org-atom.el] > > =A0To use the exporter you need a recent version of atom-syndication.el, > =A0an elisp implementation of the Atom Syndication Format. =A0You can get > =A0atom-syndication.el from github, too: > > =A0git://github.com/dmj/atom-syndication.git > > * Usage > > =A0Please see the almost complete documentation below or read via web at > > =A0[http://ictsoc.de/code/org-atom.html] > > * Backward incompatibility > > =A0If you have used an older version of the exporter you need to revise > =A0your configuration due to incompatible changes. =A0Most notably: > > =A0 =A0- in-buffer options and publishing properties have be (re)renamed > =A0 =A0 =A0to start with #+FEED and :feed instead of #+ATOM and :atom; > > =A0 =A0- support for the atom:category element is temporarily removed; > > =A0 =A0- some default values have changed: > > =A0 =A0 =A0- content is not published by default > > =A0 =A0 =A0- names of the atom:updated and atom:published property defaul= t to > =A0 =A0 =A0 =A0atom_updated and atom_published > > * Things yet to be done > > =A0Besides support of even more atom elements (e.g. use tags for the > =A0atom:category element), the exporter would require a proper > =A0documentation for the Org mode manual, and of course some real-world > =A0testing. =A0Thus I'm interested not just in bugs, glitches, > =A0inconsistencies, and complains about the exporter but some feedback > =A0about the present documentation, too. > > * Documentation > > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0Publish Atom feeds based on Org files > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > Date: 2010-06-15 18:49:21 CEST > > Table of Contents > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > 1 Exporting an Org file to Atom > =A0 =A01.1 In-buffer options > =A0 =A01.2 Headline properties > =A0 =A01.3 Export settings > =A0 =A01.4 Example > 2 Publish feeds for a web page project > =A0 =A02.1 Publish a feed for each file in the project > =A0 =A02.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. =A0The 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 > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > An Atom feed is identified by a globally unique identifier, preferably > a UUID. =A0Such an identifier must be present in a Org file supposed to > get exported or published to Atom in the =3D#+FEED_ID=3D 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 =3D#+FEED_URL=3D. =A0By 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 =3Dorg-export-html-extension=3D. > > For example a feed for the file =3Dexample.org=3D with the in-buffer > option =3D#+FEED_URL=3D set to =3Dhttp://example.tld/feed.atom=3D is expe= cted > to reference content located on the URL > =3Dhttp://example.tld/example.html=3D. > > 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 =3D#+FEED_CONTENT_URL=3D. > > Prospective feed entries are found by using the TAGS/PROP/TODO query > specified in the =3D#+FEED_MAP_ENTRIES=3D option. > > If present, the exporter uses the in-buffer options =3D#+TITLE=3D and > =3D#+DESCRIPTION=3D for the feed title and description. =A0If no title is > given, the exporter uses the file name. =A0If 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 =3D#+FEED_TITLE=3D > and =3D#+FEED_DESCRIPTION=3D. > > Atom feeds are required to have an associated author of a feed and its > entries. =A0Exporting an Org file to Atom thus always uses the author > specified with the =3D#+AUTHOR=3D option as the name of the author of a > feed. =A0If this option is not present, Org falls back to use whatever > the variable =3Duser-full-name=3D is set to. > > 1.2 Headline properties > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > A headline that matches the TAGS/PROP/TODO query for feed entries > requires at least two headline properties to be present: The =3DID=3D > property with a unique identifier of the headline (preferable a UUID) > and a property called =3Datom_published=3D containing a time stamp with > the date an entry should be considered to be published. =A0If 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 t= he publishing > date[3] > > By default Org just publishes a link to the content of feed entry > headlines. =A0If you set the customization variable > =3Dorg-atom-publish-content=3D, the whole subtree of a feed entry headlin= e > 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 > =3Datom_href_alternate=3D. Additionally you can reference URLs related to > the Atom entry by putting them into the property =3Datom_href_related=3D > and a possible source of the information present in the headline in > the property =3Datom_href_via=3D. > > 1.3 Export settings > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > The =3D#+FEED_OPTIONS=3D line is a compact1 form to specify export > settings. Here you can: > > =A0git: =A0 =A0 =A0 turn on/off usage of =3Dgit blame=3D to obtain headli= ne creation date > =A0content: =A0 turn on/off publishing content > > 1.4 Example > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > =A0#+TITLE: News about example.tld > =A0#+AUTHOR: John Doe > > =A0#+FEED_ID: f6c537d7-6733-427b-a2d5-a6a14b81a967 > =A0#+FEED_URL: http://example.tld/news.atom > =A0#+FEED_CONTENT_URL: http://example.tld/news.html > =A0#+FEED_MAP_ENTRIES: LEVEL=3D2+feed > > Calling =3Dorg-export-as-atom=3D 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. =A0While 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 > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > The function =3Dorg-publish-org-to-atom=3D can be used to create an Atom > feed for every file in a publishing project that contains at least one > feed entry headline. =A0Files that do not contain feed entry headlines > either because =3D#+FEED_MAP_ENTRIES=3D does not match or is not present > are silently skipped. > > If the publishing project property =3D:publishing-url=3D is set and a fil= e > contains feed entries but no =3D#+FEED_URL=3D or =3D#+FEED_CONTENT_URL=3D > in-buffer option, the URLs are automatically derived from this > property assuming the files in =3D:publishing-directory=3D 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 > =3D:feed-content-extension=3D. > > 2.2 Publish a combined feed for project files > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > For publishing a combined feed for all entries in a project Org > provides a sitemap function =3Dorg-atom-publish-org-as-atom-index=3D. =A0= It > iterates over all files in the project, collects prospective feed > entries and creates a combined feed in the file specified by > =3D:sitemap-file=3D. > > Obviously feed metadata must be supplied in the publishing project: > The property =3D:feed-id=3D holds the unique identifier for the feed, > =3D:feed-title=3D the feed's title, and =3D:publishing-url=3D the base UR= L of > the published project. =A0I.e. the feed and its entry's content in > =3D:base-directory=3D 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 > =3Dorg-id-method=3D > > [3] If you maintain your files in a git repository, you might > look at the customization variable > =3Dorg-atom-try-prepare-headline-git=3D. =A0If it is non-nil, Org tries t= o > obtain a date for a headline using the =3Dgit blame=3D 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 >