[Orgmode] Release 6.03

[Carsten Dominik]

Hi

release 6.03 is up on http://orgmode.org.

Enjoy!

- Carsten



Changes in Version 6.03
~~~~~~~~~~~~~~~~~~~~~~~

Overview
========

   - Description lists are now supported natively
   - Block quotes for export
   - Fontified code examples in HTML export
   - Include files for export
   - Text before the first headline is now exported by default
   - In-buffer options may now be collected in an external file
   - The in-buffer settings keywords may now be lower case
   - Completion of structure elements
   - Startup visibility can now be influenced by properties
   - Clock task history, moving entries with the running clock
   - BBDB anniversaries much faster
   - New contrib files: org-eval.el and org-mtags.el

Incompatible changes
====================

- The text before the first headline is now exported by default

  Previously, the default was to not include text in an org-mode
  buffer before the first headline.  From now on, the default it to
  include it.  If you like the old default better, customize the
  variable `org-export-skip-text-before-1st-heading' or set the
  value on a per-file basis with

  #+OPTIONS: skip:t


Details
=======

Description lists are now supported natively
--------------------------------------------

A plain list will be exported as a description list if the
first item in the list has a /term/ and the /description/,
separated by " :: ".  For example

  Emacs software by Carsten Dominik
  - RefTeX    :: Support for LaTeX Labels, References, Citations
  - CDLaTeX   :: more LaTeX functionality for Emacs
  - TeXmathp  :: checking LaTeX buffers for Math mode.
  - ORG       :: An Emacs mode for notes and projet planning.
  - CONSTANTS :: An Emacs package for inserting the definition of
                 natural constants and units into a buffer.
  - IDLWAVE   :: The Emacs modes for editing and
                 running IDL and WAVE CL files.

will be rendered as

  Emacs software by Carsten Dominik
  RefTeX
      Support for LaTeX Labels, References, Citations
  CDLaTeX
      more LaTeX functionality for Emacs
  TeXmathp
      checking LaTeX buffers for Math mode.
  ORG
      An Emacs mode for notes and projet planning.
  CONSTANTS
      An Emacs package for inserting the definition of
      natural constants and units into a buffer.
  IDLWAVE
      The Emacs modes for editing and
      running IDL and WAVE CL files.

This works now in the HTML exporter, we still need to supoort
it with the LaTeX and ASCII exporters.


Block quotes for export
-----------------------

For quoting an entire paragraph as a citation, use

   #+BEGIN_QUOTE
   Everything should be made as simple as possible,
   but not any simpler -- Albert Einstein
   #+BEGIN_QUOTE


which will render as

   Everything should be made as simple as possible,
   but not any simpler -- Albert Einstein


Fontified code examples in HTML export
--------------------------------------

You can now get code examples fontified like they would be
fontified in an Emacs Buffer, and export the result to HTML.
To do so, wrap the code examples into the following
structure:

   (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))

In the export, this will then look like this (if you are now
looking at the ASCII export and do not see anything
interesting, go and check out the HTML version at
http://orgmode.org/Changes.html).

   (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))


The string after the `BEGIN_SRC' is the name of the major emacs
mode that should be used to fontify the code example, without the
"-mode" at the end of the mode name.  For example, if you are
writing an Org tutorial with Org examples included, you would use
"org" as the language identifier - in fact, I have used just
that in the example above.

Currently this works only for HTML export, and requires the
/htmlize.el/ package, version 1.34 or later.  For other
backends, such structures are simply exported as EXAMPLE.


Include files for export
------------------------

A line like

     #+INCLUDE "file" markup lang

will lead to the inclusion of the contents of FILE at the moment
of publishing.  FILE should be surrounded by double quotes, this
is obligatory if it contains space characters.  The parameters
MARKUP and LANG are optional.  MARKUP can be "example", "quote",
or "src".  If it is "src", LANG should be the name of the Emacs
mode to be used for fontifying the code.  For example:

     Here is my /.emacs/ file:
     #+INCLUDE "~/.emacs" src emacs-lisp


The text before the first headline is now exported by default
-------------------------------------------------------------

Previously, the default was to not include text in an org-mode
buffer before the first headline.  From now on, the default it to
include it.  If you like the old default better, customize the
variable `org-export-skip-text-before-1st-heading' or set the
value on a per-file basis with

    #+OPTIONS: skip:t


In-buffer options may now be collected in an external file
----------------------------------------------------------

If you would like to share the Org setup between a number of
files, you can now store in-buffer setup in a file and simply
point to that file from each file that should read it.  If
you write in a buffer

     #+SETUPFILE: "path/to/setup.org"

then this file will be scanned for in-buffer options like
`#+STARTUP', `#+TITLE', or `#+OPTIONS'.


The in-buffer settings keywords may now be upper or lower case
--------------------------------------------------------------

From now on, it makes no difference is you write `#+STARTUP' or
`#+startup', to make these lines less imposing.  Similarly for all
other in-buffer keywords.


Completion of structure elements
--------------------------------

As a new experimental feature, Org now supports completion of
structural elements like `#+BEGIN_EXAMPLE' in a special way.
It work by typing, for example "<e" and then pressing TAB, on
an otherwise empty line.  "<e" will expand into a complete
EXAMPLE template, with the cursor positioned in the middle.
Currently supported templates are:

     <s   #+begin_src
     <e   #+begin_example
     <q   #+begin_quote
     <v   #+begin_verse
     <l   #+begin_latex
     <L   #+latex:
     <h   #+begin_html
     <H   #+html:
     <a   #+begin_ascii
     <i   #+include

This is an experimental feature, please comment!  See also
below under /org-mtags.el/.

Startup visibility can now be influenced by properties
------------------------------------------------------

When Emacs opens an Org mode buffer, the outline visibility
is set to a startup value that is taken from the variable
`org-startup-folded', or from a `#+STARTUP' setting in the
buffer.  After this has happened, the buffer will now also be
scanned for entries with a `VISIBILITY' property.  Wherever
such a property is found, the corresponding subtree will get
its visibility adjusted.  Allowed values for the property
are:

    folded    Fold the subtree
    children  Show the text after the headline, and the
              headlines of all direct children
    content   Show all headlines in the tree, but no text
              below any headline
    all       Show the entire subtree

For example, I am using this for the huge /Changes.org/ file that
is the source for the list of visible changes you are reading
right now.  The top-most entry in this file always describes the
changes in my current working version.  The start of this section
currently looks like this:

 * Version 6.03
   :PROPERTIES:
     :VISIBILITY: content
   :END:
 ** Overview


This was a proposal by Ben Alexander.

The command `C-u C-u TAB' will switch back to the startup
visibility of the buffer.

Clock task history, and moving entries with the running clock
-------------------------------------------------------------

Org now remembers the last 5 tasks that you clocked into, to
make it easier to clock back into a task after interrupting
it for another task.

- `C-u C-u C-c C-x C-i' (or `C-u C-u I' from the agenda) will
  clock into that task and mark it as current default task.

- `C-u C-c C-x C-i' (or `C-u I' from the agenda) will offer a
  list of recently clocked tasks, including the default task,
  for selection. `d' selects the default task, `i' selects
  the task that was interrupted by the task that is currently
  being clocked. `1',... selects a recent task.  When you
  select a task, you will be clocked into it.

- You can use `C-u C-c C-x C-j' to jump to any of these
  tasks.

When moving an entry using structure editing commands,
archiving commands, or the special subtree cut-and-paste
commands `C-c C-x C-w' and `C-c C-x C-y', the running clock
marker and all clock history markers will be moved with the
subtree.  Now you can start a clock in a remember buffer and
keep the clock running while filing the note away.  See also
the variable `org-remember-clock-out-on-exit'.

BBDB anniversaries much faster
------------------------------

`bbdb-anniversaries' is now much faster, thanks to a new
approach using a hash for birthdays.  Thanks to Thomas
Baumann for a patch to this effect.

New files in the contrib directory
----------------------------------

Do people think any of these should become core?

 org-eval.el
     This new module allows to include the result
     of the evaluation of Lisp code (and other scripting
     languages) into the buffer, similar to the `<lisp>' tag
     of [Emacs Wiki] and [Muse].

 org-mtags.el
     This new modules allows you to use
     Muse-like tags for some structure definitions in Org.
     For example, instead of

       #+BEGIN_EXAMPLE
       ...
       #+END_EXAMPLE

     you can write

       <example>
       ...
       </example>

     In fact, I myself find these easier to type and to look
     at.  Also, it will allow you to more easily move text
     and files back and forth between Org and Muse.  For a
     list of supported structure elements, see the commentary
     in the file [commentary in the file org-mtags.el].

     If you load this module and use the "<i" etc completion
     described above, the Muse form will automatically be
     inserted.

Bug fixes
---------

Many bug fixes