At Tue, 26 Jul 2011 13:48:30 +0200,
Bastien wrote:
> 
> > +;;      list and then filtered and sorted according to OPTIONS
> > +;;    - The first sibling on the list is changed into KEYWORD state
> > +;;    - The sibling also gets the same TRIGGER property
> > +;;      "chain-siblings-scheduled", so the chain can continue.
> 
> This should rather be "chain-find-next" here, right?

Yes thats a typo, I was trying to select a more appropriate name for it.

> > +;;    OPTIONS should be a comma separated string without spaces, and
> > +;;    can contain following options:
> > +;;    
> > +;;    - from-top      the candidate list is all of the siblings in
> > +;;                    the current subtree
> > +;;                    
> > +;;    - from-bottom   candidate list are all siblings from bottom up
> > +;;    
> > +;;    - from-current  candidate list are all siblings from current item
> > +;;                    until end of subtree, then wrapped around from
> > +;;                    first sibling
> > +;;                    
> > +;;    - no-wrap       candidate list are siblings from current one down
> 
> I'm not sure to understand the difference between "from-top" and
> "from-current", and between "from-top" and "no-wrap". 
> 
> Can you give an example?

* Parent
** TODO Item 1
** TODO Item 2
** TODO Item 3
** TODO Item 4
** NEXT Item 5 Current  (the one with TRIGGER property)
** TODO Item 6
** Item 7
** TODO Item 8
** DONE Item 9

Below are example list of candidates depending on option

from-top                  => 1,2,3,4,6,7,8
from-bottom               => 8,7,6,4,3,2,1
from-current              => 6,7,8,1,2,3,4
from-current,no-wrap      => 6,7,8

Adding todo-only will eliminate item 7 from all of above, adding
include-done will include item 9.

After inital candidate list is established as above, its sorted by priority
or effort, then 1st item is made NEXT.

> > +;;    
> > +;;    - include-done  include siblings with TODO in `org-done-keywords',
> > +;;                    they are excluded by default
> 
> The phrasing is a bit confusing to me -- perhaps removing "they are
> excluded by default" is enough.

Agree, maybe whole option can be eliminated, I had an opposite option
initially (skip-done), to have default compatible with original
trigger, but decided that skipping done may be a better default.

> > +;;    - todo-only     Only consider siblings that have TODO only, by default
> > +;;                    siblings without TODO keyword are considered too
> 
> I suggest this:
> 
>   "Only consider siblings that have a TODO keyword."
> 
> I suppose "todo-only" and "include-done" are compatible, right?

todo-only excludes items without any todo keyword, ie plain
headlines. See example above on if item 7 is included or not.

include-done forces items with a DONE/CANCELLEd keyword to be considered

> 
> What about using exclusive options like "todo-only" and
> "todo-and-done-only"?  So that you would need to use only one.

I'm fine with that, will change.
> >  
> >  (require 'org)
> > +(require 'cl)
> 
> this (eval-when-compile (require 'cl)) -- emacs has a policy of
> preventing (require 'cl) only...

I grepped *.el and saw other file using it without eval-when-compile
(it was htmlize.el i think), so I thought it was ok in contrib. My
worry was that using functions as opposite to macros needs it loaded,
since I use (remove-if) and (position)

But I just tested it on clean file and emacs -Q, and
(eval-when-compile (require 'cl)) and then using 'cl-seq functions
like remove-if seems to works fine.

I'll submit updated patch later today taken above comments inte
consideration. Attached is an org file where you can test various
options

> Thanks for further feedback on this!  If you can provide a small
> Org file where I can test the new functionalities that will help
> a lot.

Attached is a test file you can use for all the situation that you
asked clarification for. After testing this file I'm thinking maybe
from-current should be a default instead of from-top. Basically I'm
open to suggestion as to the most sensible default options. I myself
use a hook that auto-inserts TRIGGER line i want when entry becomes
next, maybe such hook should be included into org-depend also? At
least as example?