Made a bunch of changes to Org-8.0: rearranged and organized information there
authorJohn Henderson <jw.hendy@gmail.com>
Mon, 1 Apr 2013 04:41:52 +0000 (23:41 -0500)
committerJohn Henderson <jw.hendy@gmail.com>
Mon, 1 Apr 2013 04:41:52 +0000 (23:41 -0500)
to cover the upgrade process to the new exporter. Also settled on worg.git/exporters/backend as the directory that should house the information for each Worg tutorial/usage guide. Ideally, each directory will house the main guide, an example .org file, and the resultant export so users can compare the guide to their actual results.

exporters/ox-overview.org [new file with mode: 0644]
exporters/ox-template.org [new file with mode: 0644]
exporters/taskjuggler.org [deleted file]
exporters/taskjuggler/ox-taskjuggler.org [moved from org-tutorials/org-taskjuggler3.org with 68% similarity]
org-8.0.org
org-contrib/org-export-template.org [new file with mode: 0644]

diff --git a/exporters/ox-overview.org b/exporters/ox-overview.org
new file mode 100644 (file)
index 0000000..b6abbd4
--- /dev/null
@@ -0,0 +1,441 @@
+#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
+#+TITLE:      The New Org-mode Exporter Framework
+#+AUTHOR:     John Henderson
+#+EMAIL:      jw.hendy[at]gmail[dot]com
+#+LANGUAGE:   en
+#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../ox-overview.html
+#+LINK_HOME:  http://orgmode.org/worg/
+#+EXPORT_EXCLUDE_TAGS: noexport
+
+[[file:index.org][{Back to Worg's index}]]
+
+
+* Introduction
+
+As of release 8.0, Org-mode has transitioned to a new export framework, authored
+primarily (/entirely?/) by Nicolas Goaziou...
+
+#+begin_example
+
+Perhaps this could be filled in with some of the technical reasons and advantages
+of the new exporter by Nicolas or someone else familiar with with it's inner workings?
+
+#+end_example
+
+For instructions on how to upgrade from the previous Org-mode exporter, see [[file:~/org/worg/org-8.0.org][the upgrade guide]].
+
+Nicolas' official announcement of the exporter may be viewed at the [[http://article.gmane.org/gmane.emacs.orgmode/65574][Org-mode mailing list
+post]]. This document presents an overview of features, as well as a list of currently
+supported exporter backends. [[http://orgmode.org/manual/Exporting.html#Exporting][Exporting]] and [[http://orgmode.org/manual/Publishing.html#Publishing][publishing]] are also documented in the [[http://orgmode.org/manual/][Org-mode
+manual]]. 
+
+* List of Org-mode exporters
+
+Please find below a list of current Org-mode exporters, the location of the backend elisp
+file (relative to downloaded Org-mode installation directory, =org=) and links Worg and
+Org-mode manual documentation.
+
+| *Name*        | *Exporter location*                | *Worg Tutorial* | *Org-mode Manual*          |
+|---------------+------------------------------------+-----------------+----------------------------|
+| ASCII         | =./lisp/ox-ascii.el=               | ox-ascii        | [[http://orgmode.org/manual/ASCII_002fLatin_002d1_002fUTF_002d8-export.html#ASCII_002fLatin_002d1_002fUTF_002d8-export][ASCII/Latin-1/UTF-8 export]] |
+| [[https://bitbucket.org/rivanvx/beamer/wiki/Home][Beamer]]        | =./lisp/ox-beamer.el=              | [[file:~/org/worg/exporters/beamer/ox-beamer.org][ox-beamer]]       | [[http://orgmode.org/manual/Beamer-class-export.html#Beamer-class-export][Beamer class export]]        |
+| HTML          | =./lisp/ox-html.el=                | ox-html         | [[http://orgmode.org/manual/HTML-export.html#HTML-export][HTML export]]                |
+| [[http://en.wikipedia.org/wiki/ICalendar][iCalendar]]     | =./lisp/ox-icalandar.el=           | ox-icalendar    |                            |
+| [[http://www.latex-project.org/][LaTeX]]         | =./lisp/ox-latex.el=               | ox-latex        | [[http://orgmode.org/manual/LaTeX-and-PDF-export.html#LaTeX-and-PDF-export][LaTeX and PDF export]]       |
+| [[http://manpages.bsd.lv/history.html][Man]]           | =./lisp/ox-man.el=                 | ox-man          |                            |
+| [[http://daringfireball.net/projects/markdown/][Markdown]]      | =./lisp/ox-md.el=                  | ox-md           |                            |
+| [[http://opendocumentformat.org/][ODT]]           | =./lisp/ox-odt.el=                 | ox-odt          | [[http://orgmode.org/manual/OpenDocument-Text-export.html#OpenDocument-Text-export][OpenDocument Text export]]   |
+| [[http://orgmode.org/manual/Publishing.html][Publishing]]    | =./lisp/ox-publish.el=             | ox-publish      | [[http://orgmode.org/manual/Publishing.html#Publishing][Publishing]]                 |
+| [[http://www.gnu.org/software/texinfo/][Texinfo]]       | =./lisp/ox-texinfo.el=             | ox-texinfo      |                            |
+|---------------+------------------------------------+-----------------+----------------------------|
+| [[http://www.atlassian.com/software/confluence/overview/team-collaboration-software][Confluence]]    | =./contrib/lisp/ox-confluence.el=  | ox-confluence   |                            |
+| [[http://imakewebthings.com/deck.js/][Deck.js]]       | =./contrib/lisp/ox-deck.el=        | ox-deck         |                            |
+| [[http://freemind.sourceforge.net/wiki/index.php/Main_Page][Freemind]]      | =./contrib/lisp/ox-freemind.el=    | ox-freemind     | [[http://orgmode.org/manual/Freemind-export.html#Freemind-export][Freemind export]]            |
+| [[http://www.gnu.org/software/groff/][Groff]]         | =./contrib/lisp/ox-groff.el=       | ox-groff        |                            |
+| [[http://www.ctan.org/pkg/koma-script][Koma Scrlttr2]] | =./contrib/lisp/ox-koma-letter.el= | ox-koma-letter  |                            |
+| [[http://www.rssboard.org/rss-specification][RSS]]           | =./contrib/lisp/ox-rss.el=         | ox-rss          |                            |
+| [[http://meyerweb.com/eric/tools/s5/][S5]]            | =./contrib/lisp/ox-s5.el=          | ox-s5           |                            |
+| [[http://www.taskjuggler.org/][Taskjuggler]]   | =./contrib/lisp/ox-taskjuggler.el= | [[file:~/org/worg/exporters/taskjuggler/ox-taskjuggler.org][ox-taskjuggler]]  | [[http://orgmode.org/manual/TaskJuggler-export.html#TaskJuggler-export][Taskjuggler export]]         |
+|---------------+------------------------------------+-----------------+----------------------------|
+| [[http://www.docbook.org/][DocBook]]       | (1)                                | -               | -                          |
+
+- (1) DocBook export, available in previous Org-mode versions, has not currently been ported
+  to the new exporter, however the new =ox-texinfo= backend can generate DocBook
+  format. Once =file.texi= is created via =ox-texinfo=, simply execute:
+
+#+begin_example 
+makeinfo --docbook file.texi
+#+end_example
+
+
+* General Documentation
+
+/This page is in progress. Please be patient as it is updated./
+
+* TODO Add details about general export usage and information     :noexport:
+* TODO Migrate Nicolas' mailing list summary here                 :noexport:
+
+Here is the [[http://article.gmane.org/gmane.emacs.orgmode/65574][email text]] to allow for easy reference in this document. The contents of his
+email should end up in this document somehow or another, as this should serve as the
+primary source of information in addition to the manual for the exporter in general. 
+
+If you migrate some information to this actual document, please delete it so that the quote below serves as a
+body of "todo" text.
+
+*Remember:* This is just for general exporter information and usage; backend-specific
+things should be housed in their appropriate repository. If the page doesn't exist, feel
+free to create it. There's a template [[file:~/org/worg/exporters/ox-template.org][here]].
+
+#+begin_quote
+
+Table of Contents
+─────────────────
+
+1 To Whom Used the Experimental Version
+2 What’s New
+.. 2.1 New Back-Ends
+.. 2.2 Drawer Handling
+.. 2.3 Special Blocks
+.. 2.4 Improved Asynchronous Export
+.. 2.5 Smart Quotes
+.. 2.6 Cross Referencing
+.. 2.7 Lists of Tables, Lists of Listings
+3 Installation
+4 Configuration
+.. 4.1 Variables
+.. 4.2 Hooks
+.. 4.3 Filters
+.. 4.4 Forking a Back-End
+5 Caveats
+6 Footnotes
+
+
+      Hello,
+
+  I will install the new export framework along with a set of back-ends
+Wednesday evening (UTC).  Here are a few notes to help you make the
+transition.
+
+
+1 To Whom Used the Experimental Version
+═══════════════════════════════════════
+
+    The merge implies some renaming for symbols and files. More
+  precisely, “e-” is removed from symbols like variable names, functions
+  and back-ends and “org-e-” becomes “ox-” in files. To sum it up:
+
+       ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                  Old name                      New name         
+       ───────────────────────────────────────────────────────────
+                   e-latex                       latex           
+                 org-e-latex                    ox-latex         
+        org-export-latex-packages-alist  org-latex-packages-alist 
+       ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    Be sure to check filters and requires in your configuration files.
+
+
+2 What’s New
+════════════
+
+    Even though the internals are completely different, the new exporter
+  mostly behaves like its predecessor.  There are only a few noticeable
+  changes.
+
+
+2.1 New Back-Ends
+─────────────────
+
+    New back-ends come with the new export engine:
+
+  • Markdown back-end (name: `md')
+  • Texinfo back-end (name: `texinfo')
+  • Man back-end (name: `man')
+
+    Most of the other back-ends have been rewritten from scratch, too.
+
+
+2.2 Drawer Handling
+───────────────────
+
+    By default, every drawer but “properties” and “logbook” has its
+  contents exported.  See `org-export-with-drawers' variable.
+
+
+2.3 Special Blocks
+──────────────────
+
+    The `org-special-blocks.el' library, which has been moved to
+  “contrib/”, is obsolete since its features are included in the new
+  export framework.
+
+
+2.4 Improved Asynchronous Export
+────────────────────────────────
+
+    Export can be asynchronous independently on the type of the source
+  or output (temporary buffer or file).  A special interface, called
+  “The Export Stack”, is used to view the output.  See
+  `org-export-in-background' variable.
+
+
+2.5 Smart Quotes
+────────────────
+
+    All back-ends have support for “smart” quotes, according to
+  `org-export-default-language' value or the `LANGUAGE' specifications
+  in the buffer.  See `org-export-with-smart-quotes'.
+    As of now, only “de”, “en”, “es” and “fr” languages are supported,
+  but it’s easy to add more.  See `org-export-smart-quotes-alist'.  Do
+  not hesitate to contribute more languages.
+
+
+2.6 Cross Referencing
+─────────────────────
+
+    Export has now full support for cross references, through targets
+  and `#+NAME' attributes[1].  Pay attention to the following example.
+
+  ╭────
+  │ #+CAPTION: A table
+  │ #+NAME: table
+  │ | a | b |
+  │ 
+  │ #+CAPTION: Another table
+  │ #+NAME: other-table
+  │ | c | d |
+  │ 
+  │ 1. <<itm>>item 1
+  │ 2. item 2
+  │ 
+  │ Look at item [[itm]]! It happens after table [[other-table]].
+  ╰────
+
+    When exported, the last line will be displayed as:
+
+  ╭────
+  │ Look at item 1! It happens after table 2.
+  ╰────
+
+    It doesn’t depend on the back-end used.  It also references
+  footnotes, headlines, LaTeX environments…
+
+
+2.7 Lists of Tables, Lists of Listings
+──────────────────────────────────────
+
+    There is support for lists of tables and lists of listings in some
+  back-ends with the following syntax:
+
+  ╭────
+  │ #+TOC: headlines
+  ╰────
+
+  ╭────
+  │ #+TOC: tables
+  ╰────
+
+  ╭────
+  │ #+TOC: listings
+  ╰────
+
+
+3 Installation
+══════════════
+
+    There are two ways to install export back-ends.
+
+  1. You may customize `org-export-backends' variable.  It contains
+     the list of back-ends that should always be available.
+
+  2. You can also simply require the back-end libraries
+     (e.g. `(require 'ox-icalendar)' for the iCalendar back-end).
+
+    Note that with method 1, the back-ends will be loaded only when the
+  export framework is used for the first time.
+
+
+4 Configuration
+═══════════════
+
+    Previously, the export engine was configured through variables and
+  numerous hooks.  Now, there are variables, only two hooks and
+  filters. One can also easily fork a new export back-end from an
+  existing one.
+
+
+4.1 Variables
+─────────────
+
+    The easiest way to browse configurable variables should be through
+  customize interface.  Though, the old export framework is still
+  lurking in the Org shipped with Emacs.
+    As a consequence, calling “customize” will also load previous export
+  engine.  It can lead to confusion as variables in both frameworks
+  share the same suffix.  You will have to be careful and double check
+  the origin of each variable being considered.
+    Anyway, if you still want to go through this, the following command
+  will get you to the right starting point:
+
+  ╭────
+  │ M-x customize-group RET org-export RET
+  ╰────
+
+    However, I suggest to browse the source files and look after
+  `defcustom' entries.
+
+
+4.2 Hooks
+─────────
+
+    Two hooks are run during the first steps of the export process.  The
+  first one, `org-export-before-processing-hook' is called before
+  expanding macros, Babel code and include keywords in the buffer.  The
+  second one, `org-export-before-parsing-hook', as its name suggests,
+  happens just before parsing the buffer.
+    Their main use is for heavy duties, that is duties involving
+  structural modifications of the document.  For example, one may want
+  to remove every headline in the buffer during export.  The following
+  code can achieve this:
+
+  ╭────
+  │ 1  (defun my-headline-removal (backend)
+  │ 2    "Remove all headlines in the current buffer.
+  │ 3  BACKEND is the export back-end being used, as a symbol."
+  │ 4    (org-map-entries
+  │ 5     (lambda () (delete-region (point) (progn (forward-line) (point))))))
+  │ 6  (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
+  ╰────
+
+    Note that functions used in these hooks require a mandatory
+  argument, as shown at line 1.
+
+
+4.3 Filters
+───────────
+
+    Filters are lists of functions applied on a specific part of the
+  output from a given back-end.  More explicitly, each time a back-end
+  transforms an Org object or element into another language, all
+  functions within a given filter type are called in turn on the string
+  produced.  The string returned by the last function will be the one
+  used in the final output.
+    There are filters sets for each type of element or object, for plain
+  text, for the parse tree, for the export options and for the final
+  output.  They are all named after the same scheme:
+  `org-export-filter-TYPE-functions', where `type' is the type targeted
+  by the filter.
+    For example, the following snippet allows me to use non-breaking
+  spaces in the Org buffer and get them translated into LaTeX without
+  using the `\nbsp' macro:
+
+  ╭────
+  │ 1  (defun ngz-latex-filter-nobreaks (text backend info)
+  │ 2    "Ensure \" \" are properly handled in LaTeX export."
+  │ 3    (when (org-export-derived-backend-p backend 'latex)
+  │ 4          (replace-regexp-in-string " " "~" text)))
+  │ 5  (add-to-list 'org-export-filter-plain-text-functions
+  │ 6               'ngz-latex-filter-nobreaks)
+  ╰────
+
+    Three arguments must be provided to a fiter (line 1): the code being
+  changed, the back-end used, and some information about the export
+  process.  You can safely ignore the third argument for most purposes.
+  Note (line 3) the use of `org-export-derived-backend-p', which ensures
+  that the filter will only be applied when using `latex' back-end or
+  any other back-end derived from it (i.e. `beamer').
+
+
+4.4 Forking a Back-End
+──────────────────────
+
+    This is obviously the most powerful customization, since you work
+  directly at the parser level.  Indeed, complete export back-ends are
+  built as forks from other once (e.g. Markdown exporter is forked from
+  the HTML one).
+    Forking a back-end means that if an element type is not transcoded
+  by the new back-end, it will be handled by the original one.  Hence
+  you can extend specific parts of a back-end without too much work.
+    As an example, imagine we want the `ascii' back-end to display the
+  language used in a source block, when it is available, but only when
+  some attribute is non-nil, like the following:
+
+  ╭────
+  │ #+ATTR_ASCII: :language t
+  ╰────
+
+    Because the `ascii' back-end is lacking in that area, we are going
+  to create a new back-end, `my-ascii', that will do the job.
+
+  ╭────
+  │  1  (defun my-ascii-src-block (src-block contents info)
+  │  2    "Transcode a SRC-BLOCK element from Org to ASCII.
+  │  3  CONTENTS is nil.  INFO is a plist used as a communication
+  │  4  channel."
+  │  5    (let ((visiblep
+  │  6           (org-export-read-attribute :attr_ascii src-block :language)))
+  │  7      (if (not visiblep)
+  │  8          (org-export-with-backend 'ascii src-block contents info)
+  │  9        (let ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)))
+  │ 10          (concat
+  │ 11           (format
+  │ 12            (if utf8p "╭──[ %s ]──\n%s╰────" ",--[ %s ]--\n%s`----")
+  │ 13            (org-element-property :language src-block)
+  │ 14            (replace-regexp-in-string
+  │ 15             "^" (if utf8p "│ " "| ")
+  │ 16             (org-element-normalize-string
+  │ 17              (org-export-format-code-default src-block info)))))))))
+  │ 18  
+  │ 19  (org-export-define-derived-backend my-ascii parent
+  │ 20    :translate-alist ((src-block . my-ascii-src-block)))
+  ╰────
+
+    The `my-ascii-src-block' function looks at the attribute above the
+  element (line 6).  If it isn’t true, it gives hand to the `ascii'
+  back-end (line 8).  Otherwise, it creates a box around the code,
+  leaving room for the language.  A fork of `ascii' back-end is then
+  created (line 19).  It only changes its behaviour when translating
+  `src-block' type element (line 20).  Now, all it takes to use the new
+  back-end is calling the following on a buffer:
+
+  ╭────
+  │ (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
+  ╰────
+
+    It is obviously possible to write an interactive function for this,
+  install it in the export dispatcher menu, and so on.
+
+
+5 Caveats
+═════════
+
+  1. Although the old exporter files have been archived into
+     “contrib/” directory, they are not usable anymore.  Org 7.9 will be
+     the last release to provide it.
+
+  2. As a consequence, three export back-ends are not available
+     anymore: Taskjuggler, XOXO and Docbook.  About the latter, there is
+     a new back-end that produces Texinfo files, which can then be
+     converted into Docbook format with:
+
+     ╭────
+     │ makeinfo --docbook file.texi
+     ╰────
+
+  3. Export section from Org manual is now obsolete.  It is being
+     rewritten, but until this task is completed, your best source of
+     information will still be the ML or the source files.
+
+
+
+Footnotes
+─────────
+
+[1] Though, it will expect a caption to be properly numbered.
+
+#+end_quote
+
diff --git a/exporters/ox-template.org b/exporters/ox-template.org
new file mode 100644 (file)
index 0000000..ece970c
--- /dev/null
@@ -0,0 +1,83 @@
+#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
+#+TITLE:      Using the Org-mode Fill-In-Blank exporter (ox-*)
+#+AUTHOR:     Your name
+#+EMAIL:      you[at]email[dot]org
+#+LANGUAGE:   en
+#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../ox-overview.html
+#+LINK_HOME:  http://orgmode.org/worg/
+#+EXPORT_EXCLUDE_TAGS: noexport
+
+#+name: banner
+#+begin_html
+  <div id="subtitle" style="float: center; text-align: center;">
+  <p>
+  Org Mode support for <a href="http://exporter-site/">Exporter Name</a>
+  </p>
+  <p>
+  <a href="http://exporter-site/">
+  <img src="http://exporter-site/graphic.file"/>
+  </a>
+  </p>
+  </div>
+#+end_html
+
+* Template Checklist [0/9]                                        :noexport:
+  - [ ] Save this template as a new file
+    - Create new directory, =worg.git/exporters/backend/=
+    - Save as =worg.git/exporters/backend/ox-backend.org= with =C-x C-w ox-backend.org RET=
+  - [ ] Revise #+TITLE:
+  - [ ] Indicate #+AUTHOR:
+  - [ ] Add #+EMAIL:
+  - [ ] Revise banner source block [0/3]
+    - [ ] Add link to a useful exporter web site (e.g. LaTeX home page, markdown wiki
+      page, etc.)
+    - [ ] Replace "Exporter Name" with Exporter name (see table at ox-overview)
+    - [ ] Find a suitable graphic and use it to link to the language web site
+  - [ ] Write an [[Introduction]]
+  - [ ] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
+  - [ ] Overview of [[Org-mode%20features%20and%20usage%20of%20export%20backend][Org-mode features and usage of export backend]]
+  - [ ] Provide brief [[Usage%20examples][Usage examples]]
+
+* Introduction
+  - Brief description of backend (e.g. What is the native backend used for?
+  - Range of typical uses within Org Mode.
+    - 
+* Requirements and Setup
+  - Installation and configuration of language software
+  - Emacs configuration (=require('ox-*)=)
+  - Org-mode configuration (=#+options:= variables, file-keywords/variables, etc.)
+
+* Org-mode features and usage of export backend
+
+Fill in this section with specifics about how to accomplish typical goals when using this
+backend. For example:
+
+- Explanation of exporter sub-options (what appears upon =C-c C-e=)
+- Use case options and tweaking explanation
+  - Sizing/positioning images
+  - Inserting links
+  - Fontification (e.g. *word*, /word/, =word=, sub/superscript, etc.)
+  - Page breaking
+  - Inserting white space (e.g. =\vspace{Xcm}=, =<br />=, etc.)
+  - Formatting tables
+  - Styles, for example accessing css functionality or setting
+    =\usepackage[options]{package}= 
+- Other ~#+attr_backend~ options of interest
+- Converting output format to some other format (if applicable)
+
+
+* Usage examples
+  - Sample document: ideally, this would be a reproducible
+    sample document of some sort that displays a wide range of functionality.
+  - Specific walkthrough of what the options in the sample document are doing, if not
+    clearly laid out above.
+  - Specific example of fine tuning some aspect of the output (placing an image here
+    vs. there, how to control text wrap, etc.).
+
+* References
+  - Links to tutorials and other resources.
+  - Link to the ox-*.el file itself
diff --git a/exporters/taskjuggler.org b/exporters/taskjuggler.org
deleted file mode 100644 (file)
index a3042d0..0000000
+++ /dev/null
@@ -1,141 +0,0 @@
-#+TITLE: Export an Org file to TaskJuggler
-#+AUTHOR: Bastien Guerry
-
-/The content below comes from the Org 7.9.3e manual./
-
-* Introduction
-
-[[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool.  It provides an optimizing
-scheduler that computes your project time lines and resource assignments
-based on the project outline and the constraints that you have provided.
-
-The TaskJuggler exporter is a bit different from other exporters, such as
-the =HTML= and @LaTeX{} exporters for example, in that it does not export
-all the nodes of a document or strictly follow the order of the nodes in
-the document.
-
-Instead the TaskJuggler exporter looks for a tree that defines the tasks
-and optionally trees that define the resources and reports for this
-project.  It then creates a TaskJuggler file based on these trees and the
-attributes defined in all the nodes.
-
-* TaskJuggler export commands
-
-You need to have Org's =contrib/= in your Emacs =load-path= and to
-=(require 'ox-taskjuggler)= to add the TaskJuggler export.  See also the
-docstring of =org-export-backends= on how to add new backends by default.
-
-When ox-taskjuggler.el is loaded, it defines two new handlers within =C-c
-C-e= (=org-export-dispatch=):
-
-| Keybinding  |                                    |                                                                                                     |
-|-------------+------------------------------------+-----------------------------------------------------------------------------------------------------|
-| C-c C-e j J | org-export-as-taskjuggler          | Export as a TaskJuggler file                                                                        |
-| C-c C-e j o | org-export-as-taskjuggler-and-open | Export as a TaskJuggler file and then open the file with TaskJugglerUI (only for TaskJugglerUI 2.x) |
-
-* Tasks
-
-#+index: org-export-taskjuggler-project-tag
-
-Create your tasks as you usually do with Org mode.  Assign efforts to each
-task using properties (it is easiest to do this in the column view).  You
-should end up with something similar to the example by Peter Jones in
-http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
-Now mark the top node of your tasks with a tag named
-=:taskjuggler_project:= (or whatever you customized
-=org-export-taskjuggler-project-tag= to).  You are now ready to export the
-project plan with =C-c C-e J= which will export the project plan and
-open a gantt chart in TaskJugglerUI.
-
-* Resources
-
-#+index: org-export-taskjuggler-resource-tag
-
-Next you can define resources and assign those to work on specific tasks.
-You can group your resources hierarchically.  Tag the top node of the
-resources with =:taskjuggler_resource:= (or whatever you customized
-=org-export-taskjuggler-resource-tag= to).  You can optionally assign an
-identifier (named ~resource_id~) to the resources (using the standard Org
-properties commands, see the [[http://orgmode.org/org.html#Property-syntax][Property syntax]] section of the manual) or you
-can let the exporter generate identifiers automatically (the exporter picks
-the first word of the headline as the identifier as long as it is
-unique---see the documentation of =org-taskjuggler-get-unique-id=).  Using
-that identifier you can then allocate resources to tasks.  This is again
-done with the ~allocate~ property on the tasks.  Do this in column view or
-when on the task type =C-c C-x p allocate RET <resource_id> RET=.
-
-Once the allocations are done you can again export to TaskJuggler and check
-in the Resource Allocation Graph which person is working on what task at
-what time.
-
-* Export of properties
-
-The exporter also takes TODO state information into consideration, i.e., if
-a task is marked as done it will have the corresponding attribute in
-TaskJuggler (~complete 100~).  Scheduling information is also taken into
-account to set start/end dates for tasks.
-
-The exporter will also export any property on a task resource or resource
-node which is known to TaskJuggler, such as ~limits~, ~vacation~, ~shift~,
-~booking~, ~efficiency~, ~journalentry~, ~rate~ for resources or ~account~,
-~start~, ~note~, ~duration~, ~end~, ~journalentry~, ~milestone~,
-~reference~, ~responsible~, ~scheduling~, etc.@: for tasks.
-
-* Dependencies
-
-The exporter will handle dependencies that are defined in the tasks either
-with the ~ORDERED~ attribute (@pxref{TODO dependencies}), with the
-~BLOCKER~ attribute (see @file{org-depend.el}) or alternatively with a
-~depends~ attribute.  Both the ~BLOCKER~ and the ~depends~ attribute can be
-either ~previous-sibling~ or a reference to an identifier (named ~task_id~)
-which is defined for another task in the project.  ~BLOCKER~ and the
-~depends~ attribute can define multiple dependencies separated by either
-space or comma.  You can also specify optional attributes on the dependency
-by simply appending it.  The following examples should illustrate this:
-
-#+BEGIN_EXAMPLE:
-* Preparation
-  :PROPERTIES:
-  :task_id:  preparation
-  :ORDERED:  t
-  :END:
-* Training material
-  :PROPERTIES:
-  :task_id:  training_material
-  :ORDERED:  t
-  :END:
-** Markup Guidelines
-   :PROPERTIES:
-   :Effort:   2d
-   :END:
-** Workflow Guidelines
-   :PROPERTIES:
-   :Effort:   2d
-   :END:
-* Presentation
-  :PROPERTIES:
-  :Effort:   2d
-  :BLOCKER:  training_material @{ gapduration 1d @} preparation
-  :END:
-#+END_EXAMPLE:
-
-#+index: org-export-taskjuggler-default-reports
-
-TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
-allocation, etc).  The user defines what kind of reports should be
-generated for a project in the TaskJuggler file.  By default, the exporter
-will automatically insert some pre-set reports in the file.  These defaults
-are defined in =org-export-taskjuggler-default-reports=.  They can be
-modified using customize along with a number of other options.  For a more
-complete list, see =M-x customize-group RET org-export-taskjuggler RET=.
-
-Alternately, the user can tag a tree with
-=org-export-taskjuggler-report-tag=, and define reports in sub-nodes,
-similarly to what is done with tasks or resources.  The properties used for
-report generation are defined in
-=org-export-taskjuggler-valid-report-attributes=. In addition, a special
-property named ~report-kind~ is used to define the kind of report one wants
-to generate (by default, a ~taskreport~).
-
-For more information and examples see the Org-taskjuggler tutorial at
-http://orgmode.org/worg/org-tutorials/org-taskjuggler.html.
similarity index 68%
rename from org-tutorials/org-taskjuggler3.org
rename to exporters/taskjuggler/ox-taskjuggler.org
index 6ef5a40..9a5b8bb 100644 (file)
@@ -481,3 +481,145 @@ task will be determined through its priority cookie.
 [fn:5] In TaskJuggler the allocations are cumulative, the exporter
 however adds some code so that inherited allocation are ignored when
 explicitly assigning a resource.
+* TODO Incorporate/update old material into this file             :noexport:
+
+This is from ./exporters/taskjuggler.org from Bastien and needs to be added into this
+document. It comes from the 7.9.3f version of the manual.
+
+** Introduction
+
+[[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool.  It provides an optimizing
+scheduler that computes your project time lines and resource assignments
+based on the project outline and the constraints that you have provided.
+
+The TaskJuggler exporter is a bit different from other exporters, such as
+the =HTML= and @LaTeX{} exporters for example, in that it does not export
+all the nodes of a document or strictly follow the order of the nodes in
+the document.
+
+Instead the TaskJuggler exporter looks for a tree that defines the tasks
+and optionally trees that define the resources and reports for this
+project.  It then creates a TaskJuggler file based on these trees and the
+attributes defined in all the nodes.
+
+** TaskJuggler export commands
+
+You need to have Org's =contrib/= in your Emacs =load-path= and to
+=(require 'ox-taskjuggler)= to add the TaskJuggler export.  See also the
+docstring of =org-export-backends= on how to add new backends by default.
+
+When ox-taskjuggler.el is loaded, it defines two new handlers within =C-c
+C-e= (=org-export-dispatch=):
+
+| Keybinding  |                                    |                                                                                                     |
+|-------------+------------------------------------+-----------------------------------------------------------------------------------------------------|
+| C-c C-e j J | org-export-as-taskjuggler          | Export as a TaskJuggler file                                                                        |
+| C-c C-e j o | org-export-as-taskjuggler-and-open | Export as a TaskJuggler file and then open the file with TaskJugglerUI (only for TaskJugglerUI 2.x) |
+
+** Tasks
+
+#+index: org-export-taskjuggler-project-tag
+
+Create your tasks as you usually do with Org mode.  Assign efforts to each
+task using properties (it is easiest to do this in the column view).  You
+should end up with something similar to the example by Peter Jones in
+http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
+Now mark the top node of your tasks with a tag named
+=:taskjuggler_project:= (or whatever you customized
+=org-export-taskjuggler-project-tag= to).  You are now ready to export the
+project plan with =C-c C-e J= which will export the project plan and
+open a gantt chart in TaskJugglerUI.
+
+** Resources
+
+#+index: org-export-taskjuggler-resource-tag
+
+Next you can define resources and assign those to work on specific tasks.
+You can group your resources hierarchically.  Tag the top node of the
+resources with =:taskjuggler_resource:= (or whatever you customized
+=org-export-taskjuggler-resource-tag= to).  You can optionally assign an
+identifier (named ~resource_id~) to the resources (using the standard Org
+properties commands, see the [[http://orgmode.org/org.html#Property-syntax][Property syntax]] section of the manual) or you
+can let the exporter generate identifiers automatically (the exporter picks
+the first word of the headline as the identifier as long as it is
+unique---see the documentation of =org-taskjuggler-get-unique-id=).  Using
+that identifier you can then allocate resources to tasks.  This is again
+done with the ~allocate~ property on the tasks.  Do this in column view or
+when on the task type =C-c C-x p allocate RET <resource_id> RET=.
+
+Once the allocations are done you can again export to TaskJuggler and check
+in the Resource Allocation Graph which person is working on what task at
+what time.
+
+** Export of properties
+
+The exporter also takes TODO state information into consideration, i.e., if
+a task is marked as done it will have the corresponding attribute in
+TaskJuggler (~complete 100~).  Scheduling information is also taken into
+account to set start/end dates for tasks.
+
+The exporter will also export any property on a task resource or resource
+node which is known to TaskJuggler, such as ~limits~, ~vacation~, ~shift~,
+~booking~, ~efficiency~, ~journalentry~, ~rate~ for resources or ~account~,
+~start~, ~note~, ~duration~, ~end~, ~journalentry~, ~milestone~,
+~reference~, ~responsible~, ~scheduling~, etc.@: for tasks.
+
+** Dependencies
+
+The exporter will handle dependencies that are defined in the tasks either
+with the ~ORDERED~ attribute (@pxref{TODO dependencies}), with the
+~BLOCKER~ attribute (see @file{org-depend.el}) or alternatively with a
+~depends~ attribute.  Both the ~BLOCKER~ and the ~depends~ attribute can be
+either ~previous-sibling~ or a reference to an identifier (named ~task_id~)
+which is defined for another task in the project.  ~BLOCKER~ and the
+~depends~ attribute can define multiple dependencies separated by either
+space or comma.  You can also specify optional attributes on the dependency
+by simply appending it.  The following examples should illustrate this:
+
+#+BEGIN_EXAMPLE:
+** Preparation
+   :PROPERTIES:
+   :task_id:  preparation
+   :ORDERED:  t
+   :END:
+** Training material
+   :PROPERTIES:
+   :task_id:  training_material
+   :ORDERED:  t
+   :END:
+*** Markup Guidelines
+    :PROPERTIES:
+    :Effort:   2d
+    :END:
+*** Workflow Guidelines
+    :PROPERTIES:
+    :Effort:   2d
+    :END:
+** Presentation
+  :PROPERTIES:
+  :Effort:   2d
+  :BLOCKER:  training_material @{ gapduration 1d @} preparation
+  :END:
+#+END_EXAMPLE:
+
+#+index: org-export-taskjuggler-default-reports
+
+TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
+allocation, etc).  The user defines what kind of reports should be
+generated for a project in the TaskJuggler file.  By default, the exporter
+will automatically insert some pre-set reports in the file.  These defaults
+are defined in =org-export-taskjuggler-default-reports=.  They can be
+modified using customize along with a number of other options.  For a more
+complete list, see =M-x customize-group RET org-export-taskjuggler RET=.
+
+Alternately, the user can tag a tree with
+=org-export-taskjuggler-report-tag=, and define reports in sub-nodes,
+similarly to what is done with tasks or resources.  The properties used for
+report generation are defined in
+=org-export-taskjuggler-valid-report-attributes=. In addition, a special
+property named ~report-kind~ is used to define the kind of report one wants
+to generate (by default, a ~taskreport~).
+
+For more information and examples see the Org-taskjuggler tutorial at
+http://orgmode.org/worg/org-tutorials/org-taskjuggler.html.
+
index d88d9a0..8f944bc 100644 (file)
@@ -4,27 +4,31 @@
 #+LANGUAGE:  en
 #+OPTIONS: toc:t
 
-* Using the current master branch
+* Introduction
 
 #+INDEX: 8.0
 #+INDEX: exporter
 #+INDEX: migrating
 
-As of [[http://orgmode.org/cgit.cgi/org-mode.git/commit/?id%3D1cac3127c2f810e83fcc1203f1dd2b15250a687e][commit 1cac3127c]], the master branch of Org's git repository uses the
-new exporter by default.  If you use the master branch, you need to update
-your configuration and change some syntactic elements of your Org files.
+The release of Org-mode 8.0 (and the git repository master branch, as of [[http://orgmode.org/cgit.cgi/org-mode.git/commit/?id%3D1cac3127c2f810e83fcc1203f1dd2b15250a687e][commit 1cac3127c]])
+uses a new export framework, developed by Nicolas Goaziou. This document provides
+information on general changes to Org, as well as the steps needed to update your
+configuration properly.
 
 If the instructions below do not help solving your problem, please ask any
-question on the mailing list, it will help us moving forward with
-documenting everything for Org 8.0.
+question on the [[http://orgmode.org/community.html][mailing list]]. Keep in mind that the new export framework is under heavy
+development, and posting to the mailing list will help not only to resolve your issues,
+but also make sure that documentation is properly udpated for the benefit of others with
+similar issues.
+
+*Note:* This page serves as an upgrade guide for the changes widely affecting users. /Please/
+refer to the [[file:~/org/worg/exporters/ox-overview.org][Exporter Overview]] page, which contains an up to date list of
+Org-mode exporters, and links to backend-specific setup and usage details.
 
 * Files moved to =contrib/=
 
 These files have been moved to the =contrib/= directory.
 
-If you were using them, you need to add the =contrib/= directory
-of the Org distribution to the Emacs =load-path=.
-
 - =org-colview-xemacs.el=
 - =org-mew.el=
 - =org-wl.el=
@@ -33,66 +37,28 @@ of the Org distribution to the Emacs =load-path=.
 - =ox-taskjuggler.el= (was org-taskjuggler.el)
 - =ox-freemind.el= (was org-freemind.el)
 
-* Original announcement of the merge of the new exporter
+If you were using them, you need to [[http://orgmode.org/manual/Installation.html][add the =contrib/lisp= directory]]
+of the Org distribution to the Emacs =load-path=.
+
+
+* Original announcement of the new exporter
 
-Nicolas announced the merge of the new exporter into the master branch [[http://article.gmane.org/gmane.emacs.orgmode/65574][in
-this email to the list]] -- maybe you'll find answers to your questions here,
-please have a look.
+The most comprehensive overview of the new exporter may be found in Nicolas' merge
+announcement [[http://article.gmane.org/gmane.emacs.orgmode/65574][in this email]] to the mailing list. Please scan the post, as you may find
+answers to your questions there.
 
 * Updating global export configuration options
 
 Global export options start with the =org-export-*= prefix, most of them
 are in the =ox.el= file.
 
-For options starting with e.g. =org-export-html-*=, see the section below.
-
-For generic export options, most of them should not need any change.  If
+Most generic export options should not require any changes. If
 you find that a generic option is useless or broken or badly documented in
 the manual, please report it to the list.
 
-* New global keywords
+* Backend-specific configuration options
 
-** New #+TOC keyword
-
-There is a new =#+TOC= which allows adding table of contents, lists of
-tables and lists of listings at specific locations during export.
-
-#+BEGIN_SRC org
-  ,#+TOC: headlines 2
-  ,#+TOC: tables
-  ,#+TOC: listings
-#+END_SRC
-
-See the "Table of contents" section in the manual.
-
-* Syntax changes
-
-** Export snippets
-
-   Export snippets are a generalization of ~@<tag>~ concept, which has
-   been removed, and the inline version of
-   ~#+begin_backend...#+end_backend~ blocks.
-
-   Their syntax is ~@@backend:value~ where ~backend~ is the targetted
-   export backend (e.g. ~html~) and ~value~ can contain anything but
-   ~@@~.
-
-   When export is done with ~backend~, the snippet is replaced with
-   ~value~, otherwise it is removed.  Whitespace characters around
-   the construct are never deleted.
-
-** Footnote definitions
-
-   A footnote definition (not inline) can now be ended with two
-   consecutive blank lines.
-
-   As a consequence, multiple paragraphs inside can be written
-   normally, separated with blank lines, instead of relying on the
-   ~\par~ command.
-
-* Updating backend-specific configuration options
-
-Backend-specific options are defined like this:
+Backend-specific options are now defined via the convention =ox-backend-*=. For example:
 
 - =org-html-*= for =HTML= and live in =ox-html.el=
 - =org-latex-*= for =LaTeX= and live in =ox-latex.el=
@@ -102,10 +68,10 @@ There is a new variable =org-export-backends= which controls what backends
 are loaded when you lauch Org.  By default, the =ASCII=, =HTML= and =LaTeX=
 are loaded, with some others.
 
-*Updating*: In your =.emacs= you need to rename =org-export-html-*= options
-to =org-html-*= and do the same for other backends.
+** HTML-specific changes
 
-** Renaming/deleting of some HTML options
+Some html-specific options were renamed more signficantly or deleted. Examine this
+table and update accordingly: 
 
 | Org 7.9.3f (maint)                     | Master (8.0)                           |
 |----------------------------------------+----------------------------------------|
@@ -120,11 +86,11 @@ to =org-html-*= and do the same for other backends.
 | org-export-html-content-div            | Deleted                                |
 | org-export-html-html-helper-timestamp  | Deleted                                |
 
-* Updating =org-publish-project-alist=
-
-The publishing functions are not loaded until the corresponding backend has
-been loaded.  You need to update =org-publish-project-alist= and to use the
-function from the new publishing engine -- here is correspondance table:
+** Org publishing specific changes
+Some changes also specifically affect =org-publish-project-alist= settings. The publishing
+functions are not loaded until the corresponding backend has been loaded.  You need to
+update =org-publish-project-alist= and to use the function from the new publishing engine
+in the table below: 
 
 | Old publishing engine    | New publishing engine      |
 |--------------------------+----------------------------|
@@ -135,82 +101,141 @@ function from the new publishing engine -- here is correspondance table:
 
 If something does not work, please report it on the mailing list.
 
-* Other important changes
 
-1. =#+STYLE:= -> =#+HTML_HEAD:=
 
-2. =#+SETUPFILE: myfile= versus =#+INCLUDE: "myfile".=
+* Upgrading your setup
 
-   Both =#+SETUPFILE:= and =#+INCLUDE:= now need quotes around the
-   file name.  There is now also a clear difference between these two
-   statements.  The first will only read keyword statements like
-   =#+TODO:= and use this to set up the current file.  The second will
-   pull in the entire content of the file during export.  The
-   =#+INCLUDE:= statement will make every headline in the included
-   file will be a child of the headline containing the include
-   keyword.  You can overwrite this behaviour with =:minlevel= num
-   parameter.
+The practical implication of the above changes to one's Org-mode setup is two-fold:
 
-1. Attribute lines now take plists:
+- You must search your configuration for the existence of varaibles starting with
+  =org-export-= and change their names (e.g. =org-export-html-validation-link= is now
+  =org-html-validation-link=). /See sections below changes specific to the HTML and
+  Publishing backends/. 
 
-   : #+attr_latex :width 5cm
-   : #+attr_beamer :options width=5cm
+- If you use exporters in addition to =ASCII=, =HTML=, and/or =LaTeX=, you need to load them
+  explicitly in your config via one of two ways (refer to  [[http://article.gmane.org/gmane.emacs.orgmode/65574][Nicolas' announcement]], section
+  3 on Installation, for explanation of the two methods): 
+
+*1: Load exporter upon first export execution per session*
+#+begin_example
+setq org-export-backends (quote (
+       beamer
+       md
+       ...
+       taskjuggler)))
+#+end_example
+
+*2: Loading all listed exporters upon Emacs startup*
+#+begin_example
+(require 'ox-beamer)
+(require 'ox-md)
+...
+(require 'ox-taskjuggler)
+#+end_example
+
+*Note:* Please stick to /one/ of the above two methods!
 
-2. Beamer backend now interprets nested headline levels as blocks instead
-   of lists.  For some preliminary guidance you can look at [[file:exporters/beamer/ox-beamer.org][this page]].
+** Using Org 7.9.3f or earlier versions of Org
 
-* Using Org 7.9.3f or earlier versions of Org
+For users who used the new exporter prior to its integration into the current master
+branch, here are some additional steps you may need to do in order to upgrade properly:
 
 1. If you had already been using the new exporter from contrib, you should
    remove the following lines from your local.mk:
    : ORG_ADD_CONTRIB = org-e-*
-   followed by a =make clean=, before you do =git pull=.
 
-2. Export engine renamed: org-export → ox
+2. Next, issue =make clean= before =git pull=.
 
-3. Backend requires renamed: org-e-* → ox-*
+2. Export engine renamed from =org-export= to =ox=
+
+3. Backend requires renamed =org-e-*= to =ox-*=
 
 4. All backend specific variables and functions renamed:
-   - org-export-* → org-* (e.g. org-html-xml-declaration, ..)
-   - org-e-* → org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
+   - =org-export-*= to =org-*= (e.g. org-html-xml-declaration, ..)
+   - =org-e-*= to =org-*= (e.g. org-latex-classes, org-ascii-bullets, ..)
 
-5. Generic export variables retain the name org-export-*
+5. Generic export variables retain the name =org-export-*=,
    (e.g. org-export-dispatch-use-expert-ui,
    org-export-filter-headline-functions, ..)
 
-6. org-latex-to-pdf-process has been renamed to org-latex-pdf-process
+6. =org-latex-to-pdf-process= renamed =org-latex-pdf-process=
 
 7. This is a guess, export snippets and backend symbols renamed:
-   - e-<backend> → <backend>
-
-Please also read [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge.
-
-* List of current Org-mode exporters
-
-Please find below a list of current Org-mode exporters, the location of the backend elisp
-file (relative to downloaded Org-mode installation directory, =org=), and links to their
-corresponding detailed tutorial pages:
-
-| *Name*        | *Exporter location*                | *Tutorial*     |
-|---------------+------------------------------------+----------------|
-| ASCII         | =./lisp/ox-ascii.el=               | ox-ascii       |
-| [[https://bitbucket.org/rivanvx/beamer/wiki/Home][Beamer]]        | =./lisp/ox-beamer.el=              | ox-beamer      |
-| html          | =./lisp/ox-html.el=                | ox-html        |
-| [[http://en.wikipedia.org/wiki/ICalendar][iCalendar]]     | =./lisp/ox-icalandar.el=           | ox-icalendar   |
-| [[http://www.latex-project.org/][LaTeX]]         | =./lisp/ox-latex.el=               | ox-latex       |
-| [[http://manpages.bsd.lv/history.html][Man]]           | =./lisp/ox-man.el=                 | ox-man         |
-| [[http://daringfireball.net/projects/markdown/][Markdown]]      | =./lisp/ox-md.el=                  | ox-md          |
-| [[http://opendocumentformat.org/][ODT]]           | =./lisp/ox-odt.el=                 | ox-odt         |
-| [[http://orgmode.org/manual/Publishing.html][Publishing]]    | =./lisp/ox-publish.el=             | ox-publish     |
-| [[http://www.gnu.org/software/texinfo/][Texinfo]]       | =./lisp/ox-texinfo.el=             | ox-texinfo     |
-|---------------+------------------------------------+----------------|
-| [[http://www.atlassian.com/software/confluence/overview/team-collaboration-software][Confluence]]    | =./contrib/lisp/ox-confluence.el=  | ox-confluence  |
-| [[http://imakewebthings.com/deck.js/][Deck.js]]       | =./contrib/lisp/ox-deck.el=        | ox-deck        |
-| [[http://freemind.sourceforge.net/wiki/index.php/Main_Page][Freemind]]      | =./contrib/lisp/ox-freemind.el=    | ox-freemind    |
-| [[http://www.gnu.org/software/groff/][Groff]]         | =./contrib/lisp/ox-groff.el=       | ox-groff       |
-| [[http://www.ctan.org/pkg/koma-script][Koma Scrlttr2]] | =./contrib/lisp/ox-koma-letter.el= | ox-koma-letter |
-| [[http://www.rssboard.org/rss-specification][RSS]]           | =./contrib/lisp/ox-rss.el=         | ox-rss         |
-| [[http://meyerweb.com/eric/tools/s5/][S5]]            | =./contrib/lisp/ox-s5.el=          | ox-s5          |
-| [[http://www.taskjuggler.org/][Taskjuggler]]   | =./contrib/lisp/ox-taskjuggler.el= | ox-taskjuggler |
+   - =e-<backend>= to =<backend>=
+
+Again, please refer to [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge for more details.
+
+
+* New global keywords
+  
+** New #+TOC keyword
+
+In the exporting of a table of contents, options only allowed for setting the
+level of the deepest table of contents headline, like so:
+
+#+begin_src org
+  ,#+OPTIONS: TOC:2
+#+end_src
+
+Upon export, only first and second level headlines would be included in the generated
+table of contents. With the new exporter, a dedicated =#+TOC= now exists which allows for
+futher customization: adding table of contents, lists of tables, and lists of listings at
+specific locations during export. 
+
+#+BEGIN_SRC org
+  ,#+TOC: headlines 2
+  ,#+TOC: tables
+  ,#+TOC: listings
+#+END_SRC
+
+See the [[http://orgmode.org/manual/Table-of-contents.html][Table of contents]] section in the manual for more information.
+
+* Syntax changes
+
+** Export snippets
+
+   Export snippets are a generalization of ~@<tag>~ concept, which has
+   been removed, and the inline version of ~#+begin_backend...#+end_backend~ blocks.
+
+   Their syntax is ~@@backend:value~ where ~backend~ is the targetted
+   export backend (e.g. ~html~) and ~value~ can contain anything but
+   ~@@~.
+
+   When export is done with ~backend~, the snippet is replaced with
+   ~value~, otherwise it is removed.  Whitespace characters around
+   the construct are never deleted.
+
+** Footnote definitions
+
+   A footnote definition (not inline) can now be ended with two
+   consecutive blank lines.
+
+   As a consequence, multiple paragraphs inside can be written
+   normally, separated with blank lines, instead of relying on the
+   ~\par~ command.
+
+** Org-mode per-file options
+
+- The =#+STYLE= option is now specified with =#+HTML_HEAD=
+
+- Using =#+SETUPFILE: file= versus =#+INCLUDE: "file".=
+
+   Both =#+SETUPFILE:= and =#+INCLUDE:= now need quotes around the
+   file name.  There is now also a clear difference between these two
+   statements.  The first will only read keyword statements like
+   =#+TODO:= and use this to set up the current file.  The second will
+   pull in the entire content of the file during export.  The
+   =#+INCLUDE:= statement will make every headline in the included
+   file will be a child of the headline containing the include
+   keyword.  You can overwrite this behaviour with =:minlevel= num
+   parameter.
+
+- Attribute lines now take plists (similar to [[http://orgmode.org/worg/org-contrib/babel/][Babel code block syntax]]):
+
+   : #+attr_latex :width 5cm
+   : #+attr_beamer :options width=5cm
+   : #+attr_html: :width 200px
 
+- Beamer backend now interprets nested headline levels as blocks instead
+  of lists.  For more guidance, see [[file:exporters/beamer/ox-beamer.org][this page]].
 
diff --git a/org-contrib/org-export-template.org b/org-contrib/org-export-template.org
new file mode 100644 (file)
index 0000000..eedd9e6
--- /dev/null
@@ -0,0 +1,66 @@
+#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
+#+TITLE:      Language Source Code Blocks in Org Mode
+#+AUTHOR:     Your name
+#+EMAIL:      you[at]email[dot]org
+#+LANGUAGE:   en
+#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../languages.html
+#+LINK_HOME:  http://orgmode.org/worg/
+#+EXPORT_EXCLUDE_TAGS: noexport
+
+#+name: banner
+#+begin_html
+  <div id="subtitle" style="float: center; text-align: center;">
+  <p>
+  Org Mode support for <a href="http://language-site/">Language</a>
+  </p>
+  <p>
+  <a href="http://language-site/">
+  <img src="http://language-site/graphic.file"/>
+  </a>
+  </p>
+  </div>
+#+end_html
+
+* Template Checklist [0/13]                                        :noexport:
+  - [ ] Revise #+TITLE:
+  - [ ] Indicate #+AUTHOR:
+  - [ ] Add #+EMAIL:
+  - [ ] Revise banner source block [0/3]
+    - [ ] Add link to a useful language web site
+    - [ ] Replace "Language" with language name
+    - [ ] Find a suitable graphic and use it to link to the language
+      web site
+  - [ ] Write an [[Introduction]]
+  - [ ] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
+  - [ ] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
+  - [ ] Describe [[Header%20Arguments][Header Arguments]]
+  - [ ] Describe support for [[Sessions]]
+  - [ ] Describe [[Result%20Types][Result Types]]
+  - [ ] Describe [[Other]] differences from supported languages
+  - [ ] Provide brief [[Examples%20of%20Use][Examples of Use]]
+* Introduction
+  - Brief description of language.
+  - Range of typical uses within Org Mode.
+* Requirements and Setup
+  - Installation and configuration of language software
+  - Emacs configuration
+  - Org-mode configuration (org-babel-do-load-languages)
+* Org Mode Features for Language Source Code Blocks
+** Header Arguments
+   - Language-specific default values
+   - Language-specific header arguments
+** Sessions
+   - Support or not
+   - Typical use for sessions
+** Result Types
+   - Which result types are supported?
+** Other
+   - Differences from other supported languages
+* Examples of Use
+  - Hello World!
+  - Common uses
+  - Links to tutorials and other resources