[Top][All Lists]
[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
>
- Re: [Orgmode] [ANN] Org to Atom, revisited,
Scott Jaderholm <=