Release 6.17

[Carsten Dominik <carsten.dominik@gmail.com>]

Hi,

I am releasing version 6.17 of Org-mode.

Besides the footnote support discussed already extensively here,
this release also contains a new feature to make Org-mode
more usable for writing tutorials and similar documents with
code examples.  Lines in code examples can now be numbered,
and you can link to specific lines with magical highlighting
of the line when hovering the moue over the link.

Enjoy.

- Carsten


Changes in Version 6.17
=======================

Overview
=========

- Footnote support
- Line numbers and references in literal examples
- New hooks for export preprocessing
- Capture column view into a different file

Details
========

Footnote support
-----------------

Org-mode now directly supports the creation of footnotes.  In
contrast to the /footnote.el/ package, Org-mode's footnotes are
designed for work on a larger document, not only for one-off
documents like emails.  The basic syntax is similar to the one
used by /footnote.el/, i.e. a footnote is defined in a paragraph
that is started by a footnote marker in square brackets in column
0, no indentation allowed.  The footnote reference is simply the
marker in square brackets inside text.  For example:

   The Org homepage[fn:1] now looks a lot better than it used to.
   ...
   [fn:1] The link is: http://orgmode.org


Org-mode extends the number-based syntax to /named/ footnotes and
optional inline definition.  Using plain numbers as markers is
supported for backward compatibility, but not encouraged because
of possible conflicts with LaTeX syntax.  Here are the valid
references:

- [1] ::  A plain numeric footnote marker.

- [fn:name] :: A named footnote reference, where `name' is a
      unique label word or, for simplicity of automatic creation,
      a number.

- [fn:: This is the inline definition of this footnote] :: A
      LaTeX-like anonymous footnote where the definition is given
      directly at the reference point.

- [fn:name: a definition] :: An inline definition of a footnote,
      which also specifies a name for the note.  Since Org allows
      multiple references to the same note, you can then use use
      `[fn:name]' to create additional references.

Footnote labels can be created automatically, or you create names
yourself.  This is handled by the variable
`org-footnote-auto-label' and its corresponding `#+STARTUP'
keywords, see the docstring of that variable for details.

The following command handles footnotes:

- C-c C-x f :: The footnote action command.  When the cursor is
      on a footnote reference, jump to the definition.  When it is
      at a definition, jump to the (first) reference.  Otherwise,
      create a new footnote.  Depending on the variable
      `org-footnote-define-inline' (with associated `#+STARTUP'
      options `fninline' and `nofninline'), the definitions will
      be placed right into the text as part of the reference, or
      separately into the location determined by the variable
      `org-footnote-section'.
      When this command is called with a prefix argument, a menu
      of additional options is offered:
      - s :: Sort the footnote definitions by reference sequence.
             During editing, Org makes no effort to sort footnote
             definitions into a particular sequence.  If you want
             them sorted, use this command, which will also move
             entries according to `org-footnote-section'.
      - n :: Normalize the footnotes by collecting all
             definitions (including inline definitions) into a
             special section, and then numbering them in
             sequence.  The references will then also be
             numbers.  This is meant to be the final step before
             finishing a document (e.g. sending off an email).
             The exporters do this automatically, and so could
             something like `message-send-hook'.
      - d :: Delete the footnote at point, and all references to it.

- C-c C-c :: If the cursor is on a footnote reference, jump to
      the definition.  If it is a the definition, jump back to the
      reference.  When called with a prefix argument at either
      location, offer the same menu as `C-u C-c C-x f'.

- C-c C-o or mouse-1/2 :: Footnote labels are also links to the
      corresponding definition/reference, and you can use the
      usual commands to follow these links.

Org-mode's footnote support is designed so that it should also
work in buffers that are not in Org-mode, for example in email
messages.  Just bind `org-footnote-action' to a global key like
`C-c f'.

The main trigger for this development came from a hook function
written by Paul Rivier, to implement named footnotes and to
convert them to numbered ones before export.  Thanks, Paul!

Thanks also to Scot Becker for a thoughtful post bringing this
subject back onto the discussion table, and to Matt Lundin for
the idea of named footnotes and his prompt testing of the new
features.

Line numbers and references in literal examples
------------------------------------------------

Literal examples introduced with `#+BEGIN_EXAMPLE' or `#+BEGIN_SRC'
do now allow optional line numbering in the example.
Furthermore, links to specific code lines are supported, greatly
increasing Org-mode's utility for writing tutorials and other
similar documents.

Code references use special labels embedded directly into the
source code.  Such labels look like "((name))" and must be unique
within a document.  Org-mode links with the coderef cookie in the
link part will be correctly interpreted, both while working with
an Org file (internal links), and while exporting to the
different backends.  Line numbering and code references are
supported for all three major backends, HTML, LaTeX, and ASCII.
In the HTML backend, hovering the mouse over a link to a source
line will remote-highlight the referenced code line.

The options for the BEGIN lines are:

  - -n :: Number the lines in the example
  - +n :: Like -n, but continue numbering from where the previous
          example left off.
  - -r :: Remove the coderef cookies from the example, and replace
          links to this reference with line numbers.  This option
          takes only effect if either -n or +n are given as well.
          If -r is not given, coderefs simply use the label name.

Here is an example:

   #+begin_src emacs-lisp -n -r
   (defmacro org-unmodified (&rest body)                   ((def))
     "Execute body without changing `buffer-modified-p'."
     `(set-buffer-modified-p                               ((back))
       (prog1 (buffer-modified-p) ,@body)))
   #+end_src
   [[Line ((def))]] contains the macro name.  Later at line  
[[((back))]],
   backquoting is used.


When exported, this is translated to the following.  Make sure to
check this out in the HTML version of this document, at
        http://orgmode.org/Changes.html#sec-1.2.2
it looks much better there.

      1:  (defmacro org-unmodified (&rest body)
      2:    "Execute body without changing `buffer-modified-p'."
      3:    `(set-buffer-modified-p
      4:      (prog1 (buffer-modified-p) ,@body)))

    Line 1 contains the macro name.  Later at line 3,
    backquoting is used.


Thanks to Ilya Shlyakhter for proposing this feature set.  Thanks
to Sebastian Rose for the key Javascript element that made the
remote highlighting possible.

New hooks for export preprocessing
-----------------------------------
     The export preprocessor now runs more hooks, to allow
     better-timed tweaking by user functions:

- `org-export-preprocess-hook' ::
   Pretty much the first thing in the preprocessor.  But org-mode
   is already active in the preprocessing buffer.

- `org-export-preprocess-after-include-files-hook' ::
   This is run after the contents of included files have been inserted.

- `org-export-preprocess-after-tree-selection-hook' ::
   This is run after selection of trees to be exported has
   happened.  This selection includes tags-based selection, as
   well as removal of commented and archived trees.

- `org-export-preprocess-before-backend-specifics-hook' ::
   Hook run before backend-specific functions are called during  
preprocessing.

- `org-export-preprocess-final-hook' ::
   Hook for preprocessing an export buffer.  This is run as the
   last thing in the preprocessing buffer, just before returning
   the buffer string to the backend.

Capture column view into a different file
------------------------------------------

     The :id parameter for the dynamic block capturing column view
     can now truly be an ID that will also be found in a
     different file.  Also, it can be like =[file:path/to/file=], to
     capture the global column view from a different file.

     Thanks to Francois Lagarde for his report that IDs outside
     the current file would not work.