emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Orgmode] [ANN] Org to Atom, revisited


From: Scott Jaderholm
Subject: Re: [Orgmode] [ANN] Org to Atom, revisited
Date: Tue, 6 Jul 2010 23:38:01 -0600

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 <address@hidden> 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.
> address@hidden
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>



reply via email to

[Prev in Thread] Current Thread [Next in Thread]