[ANN] Org to Atom, revisited

[ANN] Org to Atom, revisited

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 8999 bytes --]


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.


[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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

Re: [ANN] Org to Atom, revisited

[Scot Becker]

[-- Attachment #1.1: Type: text/plain, Size: 33 bytes --]

Wow, David,  This is cool stuff.

[-- Attachment #1.2: Type: text/html, Size: 46 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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

Re: [ANN] Org to Atom, revisited

[Matt Lundin]

David,

David Maus <dmaus@ictsoc.de> writes:

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

Thanks. This looks great! I had grand plans a year or so ago to work on
a feed exporter, but your org-atom.el far outleaps my brief, faltering
steps in that direction. I look forward to using it.

Best,
Matt

Re: [ANN] Org to Atom, revisited

[T.F. Torrey]

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

Re: [ANN] Org to Atom, revisited

[Olivier Schwander]

Le 15 Jun 2010 18:51, David Maus a écrit:
> 
> 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.

Great work, I work it will really improve web publishing ability of
org-mode.

Some remarks below:

> [here]: http://ictsoc.de/code/org-atom/example.atom

Is there the source of this feed somewhere ? It would be nice to have a
self sufficient example.

> * Download and installation

Maybe it would be useful to have the emacs lisp fragment users need to
put in their .emacs file ? And add this part to the "Download and
install" section of the online manual.

> * Documentation

> Table of Contents
> =================
> 1 Exporting an Org file to Atom

There is no Install section here, but there is one in the online
version.

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

Maybe it should be better to extract timestamp from the usual timestamp
below headlines, like this one:

* Some title
  [2010-06-16 mer. 14:19]

or

* DONE Some title
  CLOSED: [2010-06-16 mer. 14:19]

Actually, with this solution, it would be better to remove the timestamp
used from the export, since it will displayed by the reader.

> 1.3 Export settings
> ====================
>   content:   turn on/off publishing content

When content is t, the headline is exported both in title and in
content, is this a feature or a bug ? If it's a feature, it should be
nice to have an option to disable it.

Cheers,

Olivier

Re: [ANN] Org to Atom, revisited

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 2881 bytes --]

Olivier Schwander wrote:

>> [here]: http://ictsoc.de/code/org-atom/example.atom

>Is there the source of this feed somewhere ? It would be nice to have a
>self sufficient example.

I've uploaded the source of the example feed to

http://ictsoc.de/code/org-atom/example.org

But it's really as straightforward as the simple example in the
documentation.

>> * Download and installation

>Maybe it would be useful to have the emacs lisp fragment users need to
>put in their .emacs file ? And add this part to the "Download and
>install" section of the online manual.

I'll put more detailed install instructions there as soon as there is
a decision about including org-atom into Org or not (yet).

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

>Maybe it should be better to extract timestamp from the usual timestamp
>below headlines, like this one:

>* Some title
>  [2010-06-16 mer. 14:19]

>or

>* DONE Some title
>  CLOSED: [2010-06-16 mer. 14:19]

>Actually, with this solution, it would be better to remove the timestamp
>used from the export, since it will displayed by the reader.

The problem is, that the Atom specification requires an entry to have
at least a atom:updated element.  Thus there must be timestamp
somewhere.  Binding the timestamp to a special position in Org mode
markup would limit the functionality of the exporter.

However: I understand that it could be reasonable to not use a
property, but an already present timestamp.  What about something like
this:

The name of the published and updated property can be customized.  It
can either be a string with the property name or the symbol
'timestamp_ia.  If it is this symbol, the exporter uses the first
inactive timestamp of a headline.  If the headline does not have an
inactive timestamp, the exporter throws an error.


>> 1.3 Export settings
>> ====================
>>   content:   turn on/off publishing content

>When content is t, the headline is exported both in title and in
>content, is this a feature or a bug ? If it's a feature, it should be
>nice to have an option to disable it.

Hah!  Good catch.  Never paid attention to this.  Just pushed a commit
that removes the title in the content element.

Thanks for the comment and suggestions.

  -- David

--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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

Re: [ANN] Org to Atom, revisited

[T.F. Torrey]

On 06/18/2010 09:03 AM, David Maus wrote:
> Olivier Schwander wrote:
>
>>> [here]: http://ictsoc.de/code/org-atom/example.atom
>
>> Is there the source of this feed somewhere ? It would be nice to have a
>> self sufficient example.
>
> I've uploaded the source of the example feed to
>
> http://ictsoc.de/code/org-atom/example.org
>
> But it's really as straightforward as the simple example in the
> documentation.
>
>>> * Download and installation
>
>> Maybe it would be useful to have the emacs lisp fragment users need to
>> put in their .emacs file ? And add this part to the "Download and
>> install" section of the online manual.
>
> I'll put more detailed install instructions there as soon as there is
> a decision about including org-atom into Org or not (yet).
>
>>> 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]
>
>> Maybe it should be better to extract timestamp from the usual timestamp
>> below headlines, like this one:
>
>> * Some title
>>   [2010-06-16 mer. 14:19]
>
>> or
>
>> * DONE Some title
>>   CLOSED: [2010-06-16 mer. 14:19]
>
>> Actually, with this solution, it would be better to remove the timestamp
>> used from the export, since it will displayed by the reader.
>
> The problem is, that the Atom specification requires an entry to have
> at least a atom:updated element.  Thus there must be timestamp
> somewhere.  Binding the timestamp to a special position in Org mode
> markup would limit the functionality of the exporter.
>
> However: I understand that it could be reasonable to not use a
> property, but an already present timestamp.  What about something like
> this:
>
> The name of the published and updated property can be customized.  It
> can either be a string with the property name or the symbol
> 'timestamp_ia.  If it is this symbol, the exporter uses the first
> inactive timestamp of a headline.  If the headline does not have an
> inactive timestamp, the exporter throws an error.

This would be a welcome addition. I would use it, and perhaps it would 
entice RMS to adopt Org Mode as well. It's pretty close to what he  uses 
for his political notes:
http://www.stallman.org/archives/2010-mar-jun.html

>>> 1.3 Export settings
>>> ====================
>>>    content:   turn on/off publishing content
>
>> When content is t, the headline is exported both in title and in
>> content, is this a feature or a bug ? If it's a feature, it should be
>> nice to have an option to disable it.
>
> Hah!  Good catch.  Never paid attention to this.  Just pushed a commit
> that removes the title in the content element.
>
> Thanks for the comment and suggestions.
>
>    -- David
>
> --
> OpenPGP... 0x99ADB83B5A4478E6
> Jabber.... dmjena@jabber.org
> Email..... dmaus@ictsoc.de
>
>
>
> _______________________________________________
> 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

Org Mode gets better all the time. Thanks again.

- Terry

Re: [ANN] Org to Atom, revisited

[Scott Jaderholm]

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

Re: [ANN] Org to Atom, revisited

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 2075 bytes --]

Hi Scott,

Scott Jaderholm wrote:
>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.

Yes, sorry.  I am behind with revising the documentation and as it
turned out, the sitemap function was completely broken.

I've pushed a fix for the sitemap function yesterday[1] and my current
(not yet published) section about the sitemap function reads like
this:

,----
| Org's Atom exporter provides a sitemap function to publish a single
| combined feed for all files in the publishing project.  To use this
| function you have to provide the mandatory feed meta data by setting
| the property =:publishing-url= to the base URL of the published
| project.  The sitemap functions assumes, that all files in the
| project's =:base-dir= are published relative to this URL and will
| create the feed's links pointing to the appropriate locations.
|
| If you prefer an ID for the feed that is distinct from the feed's URL,
| you can provide the ID with the =:feed-id= property.
|
| The name of the feed can be set by the =:sitemap-file= property and
| defaults to =sitemap.atom=.
|
| For example, this minimal project definition will publish a combined
| feed for all entries found in the project's files
|
| #+begin_src emacs-lisp
|   ("sitemap-feed"
|    :base-directory "~/project/webpage/"
|    :base-extension "org"
|    :publishing-directory "~/www/"
|    :auto-index t
|    :publishing-url "http://example.org/"
|    :sitemap-function org-atom-publish-feed-sitemap)
| #+end_src
`----

So, the minimal definition
requires :publishing-url, :sitemap-function, and :auto-index to turn
on the sitemap.

Does this makes the sitemap publishing process somewhat clearer?

Best,
  -- David

[1] http://github.com/dmj/dmj-org-mode/raw/org-atom/lisp/org-atom.el
--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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