[Orgmode] Org-mode version 5.01

[Carsten Dominik]

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 address@hidden  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: address@hidden::@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!