emacs-orgmode
[Top][All Lists]
Advanced

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

[Orgmode] Release 6.17


From: Carsten Dominik
Subject: [Orgmode] Release 6.17
Date: Sun, 4 Jan 2009 09:13:56 +0100

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.





reply via email to

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