Org-mode version 5.01

[Carsten Dominik <dominik@science.uva.nl>]

Hi,

I am releasing Org-mode 5.01.  It is available at my website

    http://www.astro.uva.nl/~dominik/Tools/org

and also through Emacs CVS.

I am pretty excited about this release, a new major version.

First: Credit where credit is due:

Much of this was triggered by the thread "Duration Tally"
on emacs-orgmode@gnu.org.  Many thanks to

- Edward DeVilla for coming up with the idea of properties.

- Russel Adams for mentioning an "additional level of folding"
   to be used for capturing properties.  This trigger has become
   the new "Drawer" feature.

- Scott Jaderholm for pointing out the advantages of column view.

- Raman for suggesting a minor mode that exports org-mode
   structure editing to arbitrary modes.

There are important changes, so unless you plan to read the manual
in the near future, I'd advise you carefully read the notes below.

Enjoy!

- Carsten

Changes in version 5.01
-----------------------

* Overview

   - A new minor mode, orgstruct-mode, exports the Org-mode
     structure editing commands into any other mode.

   - DRAWERS are a new level off folding for special sections
     that should stay closed during visibility cycling and only
     open if explicitly asked.

   - Entries can now have PROPERTIES.

   - A COLUMN VIEW implementation allows to easily view and edit
     the properties of a hierarchy of entries.

   - Formula evaluation in the spreadsheet is more consistent
     now.  Properties and per-file constants can be used during
     evaluation.

   - Bug fixes and minor changes.

* Incompatible changes

   - When using LEVEL=N in a tags search, things have changed if
     you are also using `org-odd-levels-only'.  If you are using
     only odd levels (i.e. 1 or 3 or 5... stars), LEVEL=2 will
     now refer to 3 stars, LEVEL=3 to 5 stars etc.  Many thanks
     to Leo (or blame him if you must) who has convinced me
     that this is the better convention.

* Details

   + Orgstruct minor mode

     There is a new minor mode, orgstruct-mode.  This modes works
     in a similar way as Orgtbl-mode.  It can be used to export
     the Org-mode structure-editing commands into arbitrary major
     modes in Emacs.  For example, you can use it in Mail-mode to
     easily create lists.

     The functionality in Orgstruct mode is only active, if the
     cursor is in a line that looks either like a headline, or
     like the first line of a plain list item.  Then the commands
     `TAB', `M-cursor', `M-S-cursor', `M-RET', `M-S-RET', `C-c ^',
     `C-c C-c', and `C-c -' will do structure-related editing just
     like in Org-mode.  If the cursor is not in such a line, all
     these keys will do whatever the major mode or other active
     minor modes have assigned to them.

     Orgstruct-mode is the result of a proposal by Raman, quite
     some time ago.  It has taken a long time, but here is finally
     the promised implementation.

   + Drawers

     The new concept of /drawers/ allows to create sections
     that remain folded during visibility cycling.  Drawers need
     to be configured using the variable `org-drawers'.  A drawer
     starts with a line containing only the name of the drawer
     bracketed by colons. It ends with :END:.  For example,
     after setting

        (setq org-drawers '("PROPERTIES" "HIDDEN"))

     you can then create drawers like this:

        :HIDDEN:
          here is some stuff that remains hidden
          unless TAB is pressed directly in that line
        :END:

     The PROPERTIES drawer has special meaning for ORG-mode, it
     contains properties of an entry (see below).

   + Properties and Column View

     - Entries in Org-mode can now have arbitrary /properties/
       associated with them.  Org-mode handles some default
       properties like the TODO state, the priority, the local
       tags, and planning information like DEADLINE and SCHEDULED.
       In addition, you can assign arbitrary properties by creating
       a property drawer and inserting a line like

          :PROPNAME: This is the value of the property

       Org-mode has an API for properties, if you want to write a
       program using properties, use the functions
       `org-entry-properties', `org-entry-get', `org-entry-put',
       and `org-entry-delete'.

     - Planning information like DEADLINE can be hidden in the
       properties drawer.

       If the PROPERTIES drawer starts in the first line after a
       headline, also the DEADLINE, SCHEDULED and CLOCK information
       will be inserted inside the drawer.  If no PROPERTIES drawer
       is present, or if it does not start in the line right after
       the headline, this information remains in the lines directly
       after the headline, outside the drawer.

     - TAGS searches can now also query properties.  For example,
       the search

          LEVEL=3+BOSS+ASSIGNED="Hans"/WAITING

       will find entries that
       - are level 3
       - have the tag BOSS
       - have an ASSIGNED property with the value "Hans"
       - are TODO status WAITING.

         So here is an entry that will match:

            *** WAITING Clean up the factory     :BOSS:
                :PROPERTIES:
                :ASSIGNED:    Hans
                :END:

         You may also use a regular expression to match against a
         property value.  For example, to find stuff assigned to Hans
         or Sarah, use

            ASSIGNED={^\(Hans\|Sarah\)$}

     - Column View is a special way to look at property values in
       tabular form.  Column View can be used in any org-mode
       file, and also in any agenda buffer.  It works by placing
       an overlay over each headline (or agenda line) that shows a
       table of selected properties.  You can look at and edit
       properties from this view.  Which properties are shown in
       the table must be set up using the COLUMNS property.  You
       can set up different property columns on different levels
       of an outline tree.  For example:

          * People
            :PROPERTIES:
            :COLUMNS: %25ITEM %Name
            :END:
          ** Family
             :PROPERTIES:
             :COLUMNS: %25ITEM %Name %3Age
             :END:
          *** Sam
              Info about Sam, including a property list with Name and 
Age.
          *** Sarah
              Info about Sarah, including a property list with Name and 
Age.
          ** Office
             :PROPERTIES:
             :COLUMNS: %25ITEM %Name %Function %Salary
             :END:
          *** Boss
              Info about the Boss, including a property list with Name,
              Function and Salary (if only we knew....).

       Now we have defined three different sets of columns.  If
       you switch to column view in the /Family/ section, you
       will get a different table than if you do it in the
       /Office/ section.  However, if you switch to column
       view with the cursor on the /People/ section, the
       table will cover all entries, but contain only the
       /Name/.

     - Properties can be used in table formulas.  To access the
       value of the property :XYZ:, use $PROP_XYZ.  The property
       needs to be defined in the hierarchy above the table, not
       necessarily in the same entry as the table.  This was a
       request by Eddward.  File-wide constants can be defined with
       #+CONSTANTS, see below.

     - Things that still need to be sorted out about drawers,
       properties and column view - comments and suggestions
       welcome!

       + How to deal with drawers and properties in HTML and ASCII
         export?
       + What key could be used to insert an empty property drawer
         into an entry?  Where exactly should it be inserted?
       + Right now column view is invoked through the command C-c
         C-x C-c.  It is too easy to type C-x C-c by mistake, and
         that causes Emacs to quit.  Suggestions for a different
         key?
       + Fontification of drawers and properties is not good yet.
         Any suggestions for better defaults?
       + Mouse support for editing properties in column view would
         be nice - maybe Piotr is interested to add this to
         org-mouse.el?

   + Spreadsheet

     - In the spreadsheet, the evaluation of formulas has changed.
       Previously, first the column formulas would be evaluated
       everywhere, and then the field formulas would kick in, and
       in some cases overwrite the results of column formulas in
       the appropriate fields.  This had the side effect that some
       formulas might always use the wrong, intermediate content of
       a field that is computed both by a column and a field
       formula.

       From now on, column formulas will no longer temporarily
       overwrite field formulas.  This gives much more consistent
       results.  For example you can now finally have a column of
       increasing numbers by setting the first field to a fixed
       number, and let the rest follow from a column formula.

       Here is an example

          | 1 |
          | 2 |
          | 3 |
          #+TBLFM: $1=@-1+1::@1$1=1

     - Constants for formulas in spreadsheets are globally defined
       with the variable `org-table-formula-constants'.  File-local
       constants can now be set with a line like:

          #+CONSTANTS: c=299792458.  pi=3.14  eps=2.4e-6

   + Minor changes

     - When entries are archived, a timestamp for the moment of
       archiving is added to the line with planning information.
       It looks like this:

        ARCHIVED: [2007-07-02 Mon 11:34]

       Thanks to J. David Boyd for constructive comments.

     - Bug fixes

       Many bugs are fixed, as usually all the ones where I replied
       "fixed" on emacs-orgmode.  If you reported one of these
       bugs, please check if it really has disappeared in the new
       version, and complain if not.  Thanks!