emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: "Tom Breton (Tehom)" <tehom@panix.com>
Cc: emacs-orgmode@gnu.org
Subject: Docs submitted (Was Re: Advice sought on managing decision alternatives.)
Date: Mon, 9 Feb 2009 22:14:13 -0500 (EST)	[thread overview]
Message-ID: <1555.24.62.30.15.1234235653.squirrel@mail.panix.com> (raw)
In-Reply-To: <8BD25355-1218-4DB5-9C85-77EA011540D0@uva.nl>

[-- Attachment #1: Type: text/plain, Size: 534 bytes --]

Hi, Carsten.

> Well, some ASCII documentation could be inserted into org-choose.el
> as a file commentary.  If you use a standard header with keywords
> for the finder (M-x finder-commentary and friends), that would be
> useful.
>
> Tutorials on Worg are usually written in Org, but you can upload
> any format you like (or send it it me) and we wil publish it there.

OK, I've add comments, keywords, and some docstrings I forgot to
org-choose.el, and I wrote a standalone doc.  Both are attached.

Tom Breton (Tehom)

[-- Attachment #2: docs.org-choose.el.diff --]
[-- Type: application/octet-stream, Size: 5874 bytes --]

*** old-org-choose.el	2009-02-09 18:25:51.000000000 -0500
--- org-choose.el	2009-02-09 20:47:47.000000000 -0500
***************
*** 5,11 ****
  ;; Copyright (C) 2009  Tom Breton (Tehom)
  
  ;; Author: Tom Breton (Tehom)
! ;; Keywords: 
  
  ;; This file is free software; you can redistribute it and/or modify
  ;; it under the terms of the GNU General Public License as published by
--- 5,11 ----
  ;; Copyright (C) 2009  Tom Breton (Tehom)
  
  ;; Author: Tom Breton (Tehom)
! ;; Keywords: outlines, convenience
  
  ;; This file is free software; you can redistribute it and/or modify
  ;; it under the terms of the GNU General Public License as published by
***************
*** 24,29 ****
--- 24,64 ----
  
  ;;;_ , Commentary:
  
+ ;; This is code to support decision management.  It lets you treat a
+ ;; group of sibling items in org-mode as alternatives in a decision.
+ 
+ ;; There are no user commands in this file.  You use it by:
+ ;;   * Loading it (manually or by M-x customize-apropos org-modules)
+ 
+ ;;   * Setting up at least one set of TODO keywords with the
+ ;;     interpretation "choose" by either:
+ 
+ ;;     * Using the file directive #+CHOOSE_TODO:
+ 
+ ;;       * For instance, "#+CHOOSE_TODO: NO(,-) MAYBE(,0) YES"
+ 
+ ;;     * Or by M-x customize-apropos org-todo-keywords
+ 
+ ;;   * Operating on single items with the TODO commands.
+ 
+ ;;     * Use C-S-right to change the keyword set.  Use this to change to
+ ;;       the "choose" keyword set that you just defined.
+ 
+ ;;     * Use S-right to advance the TODO mark to the next setting.  
+ 
+ ;;       For "choose", that means you like this alternative more than
+ ;;       before.  Other alternatives will be automatically demoted to
+ ;;       keep your settings consistent.
+ 
+ ;;     * Use S-left to demote TODO to the previous setting.  
+ 
+ ;;       For "choose", that means you don't like this alternative as much
+ ;;       as before.  Other alternatives will be automatically promoted,
+ ;;       if this item was all that was keeping them down.
+ 
+ ;;     * All the other TODO commands are available and behave essentially
+ ;;       the normal way.
+ 
  ;;;_ , Requires
  
  (require 'org)
***************
*** 194,200 ****
  
  ;;;_  . org-choose-conform-after-promotion
  (defun org-choose-conform-after-promotion (entry-pos keywords highest-ok-ix)
!    ""
     
     (unless
        ;;Skip the entry that triggered this by skipping any entry with
--- 229,235 ----
  
  ;;;_  . org-choose-conform-after-promotion
  (defun org-choose-conform-after-promotion (entry-pos keywords highest-ok-ix)
!    "Conform the current item after another item was promoted"
     
     (unless
        ;;Skip the entry that triggered this by skipping any entry with
***************
*** 215,221 ****
  (defun org-choose-conform-after-demotion (entry-pos keywords
  					       raise-to-ix
  					       old-highest-ok-ix) 
!    ""
     (unless
        ;;Skip the entry that triggered this.
        (= (point) entry-pos)
--- 250,256 ----
  (defun org-choose-conform-after-demotion (entry-pos keywords
  					       raise-to-ix
  					       old-highest-ok-ix) 
!    "Conform the current item after another item was demoted"
     (unless
        ;;Skip the entry that triggered this.
        (= (point) entry-pos)
***************
*** 232,240 ****
  	    (org-todo 
  	       (nth raise-to-ix keywords))))))
  
! ;;;_ , org-choose-keep-sensible (the trigger-hook function)
  (defun org-choose-keep-sensible (change-plist)
!    ""
  
     (let*
        (  (from (plist-get change-plist :from))
--- 267,276 ----
  	    (org-todo 
  	       (nth raise-to-ix keywords))))))
  
! ;;;_ , org-choose-keep-sensible (the org-trigger-hook function)
  (defun org-choose-keep-sensible (change-plist)
!    "Bring the other items back into a sensible state after an item's
! setting was changed."
  
     (let*
        (  (from (plist-get change-plist :from))
***************
*** 327,340 ****
  ;;;_ , Getting the default mark
  ;;;_  . org-choose-get-index-in-keywords
  (defun org-choose-get-index-in-keywords (ix all-keywords)
!    "Return index of current entry."
     (if ix
        (position ix all-keywords
  	 :test #'equal)))
  
  ;;;_  . org-choose-get-entry-index
  (defun org-choose-get-entry-index (all-keywords)
!    "Return index of current entry."
  
     (let*
        ((state (org-entry-get (point) "TODO")))
--- 363,376 ----
  ;;;_ , Getting the default mark
  ;;;_  . org-choose-get-index-in-keywords
  (defun org-choose-get-index-in-keywords (ix all-keywords)
!    "Return the index of IX in ALL-KEYWORDS."
     (if ix
        (position ix all-keywords
  	 :test #'equal)))
  
  ;;;_  . org-choose-get-entry-index
  (defun org-choose-get-entry-index (all-keywords)
!    "Return the index of the current entry."
  
     (let*
        ((state (org-entry-get (point) "TODO")))
***************
*** 377,383 ****
  ;;;_  . org-choose-highest-ok
  
  (defun org-choose-highest-other-ok (ix data)
!    ""
  
     (let
        (		
--- 413,421 ----
  ;;;_  . org-choose-highest-ok
  
  (defun org-choose-highest-other-ok (ix data)
!    "Return the highest index that any choose mark can sensibly have,
! given that another mark has index IX.
! DATA must be a `org-choose-mark-data.'."
  
     (let
        (		
***************
*** 398,407 ****
  ;;;_  . org-choose-get-default-mark-index
  
  (defun org-choose-get-default-mark-index (data) 
!    "Get the index of the default mark in a choose interpretation.
  
! Args are in the same order as the fields of
! `org-choose-mark-data.' and have the same meaning."
  
     (or
        (let
--- 436,444 ----
  ;;;_  . org-choose-get-default-mark-index
  
  (defun org-choose-get-default-mark-index (data) 
!    "Return the index of the default mark in a choose interpretation.
  
! DATA must be a `org-choose-mark-data.'."
  
     (or
        (let

[-- Attachment #3: docs.org-choose-docs.org --]
[-- Type: application/octet-stream, Size: 4966 bytes --]

* Org-choose

Org-choose supports decision management.

** General 

org-choose operates on a group of sibling items in org-mode.  It
treats them as potential choices in some decision.

The items have marks such as "CHOSEN", "MAYBE", or "REJECTED".  You
can configure the set of marks.  The marks behave similarly to TODO
marks.  org-choose keeps the marks in a consistent overall state.

A sibling item that has no mark is assumed to not represent an
alternative; so is an item with a mark from another keyword set.

** How to use it

*** Overview of use

org-choose contains no user commands.  You use it by:

  * Loading it

  * Setting up at least one set of TODO keywords with the
    interpretation "choose".

  * Operating on single items with the TODO commands.

*** Loading it (No surprises here)

The easiest way is by 

	M-x customize-apropos org-modules

Scroll down to "External packages" at the end of the list.  Insert a
new one, and fill in "org-choose".  This will cause it to be loaded
every time you start org-mode.

You'll still have to load it manually the first time.

Of course, you can also just try it out by loading it manually.

*** Setting up a keyword set

To use org-choose, you need to set up at least one set of TODO
keywords with the interpretation "choose".  There are two basic ways.
Both are essentially the same as for other TODO marks.

    * By using the file directive #+CHOOSE_TODO: 

    * By M-x customize-apropos org-todo-keywords

**** The markings

The format of marks is essentially that of ordinary TODO marks.  The
marks can have parenthesized arguments that indicate key bindings and
similar shortcuts.

In addition, they can optionally have a second argument.  The
arguments are separated by a comma.  The second argument can have one
of 3 values:

 * 0 :: The mark with this argument is the default mark.  New items
        will have that mark, if they are from this TODO keyword set.

 * - :: This mark with this argument is at the bottom of the "NOT
        CHOSEN" range (See [[id:3698439c-93d5-4242-b566-96e760f64108][About consistent state]]).  It should be
        lower than the default mark (0). If this is omitted,
        org-choose will not try to keep marks in consistent state.

 * + :: This mark with this argument is at the top of the "CHOSEN"
        range.  It should be higher than the default mark (0). If this
        is omitted, org-choose will use the highest mark instead.

No value should be given twice.

This works even if there is no first argument; just give an empty
string as the first argument.

***** Examples of marks

 * REJECTED :: Makes a mark whose text is "REJECTED".
 * MAYBE(,0) :: Makes a mark whose text is "MAYBE".  It is the default
                mark.
 * CHOSEN(c,+) :: Makes a mark whose text is "CHOSEN".  It is the top
                  of the high range.  The key "c" will select it,
                  exactly as the usual TODO hotkey behavior.

**** Examples of mark specs

 * #+CHOOSE_TODO: NO(,-) MAYBE(,0) YES
 * #+CHOOSE_TODO: REJECTED(r) NOT_CHOSEN(n,-) MAYBE(,0) LEANING_TOWARDS(l) CHOSEN(c,+)

*** Operating on items

You can operate on single items with the usual TODO commands.

    * Use C-S-right to change the keyword set.  Use this to change to
      the "choose" keyword set that you just defined.

    * Use S-right to advance the TODO mark to the next setting.  

      For "choose", that means you like this alternative more than
      before.  Other alternatives will be automatically demoted to
      keep your settings consistent.

    * Use S-left to demote TODO to the previous setting.  

      For "choose", that means you don't like this alternative as much
      as before.  Other alternatives will be automatically promoted,
      if this item was all that was keeping them down.

    * All the other TODO commands are available and behave essentially
      the normal way.



** About consistent state
   :PROPERTIES:
   :ID:       3698439c-93d5-4242-b566-96e760f64108
   :END:

org-choose tries to keep each group of items in a consistent state.

It knows about 2 ranges of marks that relate to each other in mirror
image fashion.  We can call them the "CHOSEN" range and the "NOT
CHOSEN" range.

If some item is marked in the "CHOSEN" range, other items can't be
marked higher than the mirror-corresponding entry in the "NOT CHOSEN"
range.

*** An example

For this example, assume we're using the marks from the second example
spec,

	"REJECTED(r) NOT_CHOSEN(n,-) MAYBE(,0) LEANING_TOWARDS(l)
	CHOSEN(c,+)"

Then org-choose enforces the following constraints:

| If any   |   | then the other |   |
| item is: |   | items can't be |   |
|          |   | higher than:   |   |
|----------+---+----------------+---|
| CHOSEN   | 1 | NOT CHOSEN     | 4 |
| FAVORED  | 2 | MAYBE          | 3 |
|----------+---+----------------+---|


** Credits

org-choose was written by Tom Breton, with much-appreciated advice
from Carsten Dominik.


[-- Attachment #4: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

  reply	other threads:[~2009-02-10  3:14 UTC|newest]

Thread overview: 55+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20090101170227.C707734803@mail2.panix.com>
2009-01-01 22:53 ` Feature request and patch - blocked TODO to say BLOCKED Tom Breton (Tehom)
2009-01-09  8:16   ` Carsten Dominik
2009-01-15  2:34     ` Tom Breton (Tehom)
2009-01-17  8:01       ` Carsten Dominik
2009-01-19  3:33     ` Advice sought on managing decision alternatives Tom Breton (Tehom)
2009-01-22 11:15       ` Carsten Dominik
2009-01-31  4:21         ` Tom Breton (Tehom)
2009-01-31  5:41           ` Carsten Dominik
2009-01-31 18:36             ` Tom Breton (Tehom)
2009-02-01 15:54               ` James TD Smith
2009-02-06 13:08           ` Carsten Dominik
2009-02-06 16:16             ` William Henney
2009-02-06 20:07             ` Tom Breton (Tehom)
2009-02-07  0:18               ` Carsten Dominik
2009-02-07 20:46                 ` Tom Breton (Tehom)
2009-02-08 13:06                   ` Carsten Dominik
2009-02-08 20:25                     ` Tom Breton (Tehom)
2009-02-09  6:42                       ` Carsten Dominik
2009-02-10  3:14                         ` Tom Breton (Tehom) [this message]
2009-02-10  7:55                           ` Docs submitted (Was Re: Advice sought on managing decision alternatives.) Carsten Dominik
2009-02-24  0:51                             ` org-choose bugfix Tom Breton (Tehom)
2009-02-24  3:05                               ` Manish
2009-04-07  0:13                                 ` Tom Breton (Tehom)
2009-04-08 13:13                                   ` Carsten Dominik
2009-02-24  5:51                               ` Carsten Dominik
2009-02-10  8:46                           ` Docs submitted (Was Re: Advice sought on managing decision alternatives.) Manish
2009-02-10  9:12                             ` Carsten Dominik
2009-02-10 10:26                               ` Manish
2009-02-10 22:48                                 ` Tom Breton (Tehom)
2009-02-12 12:50                                   ` Manish
2009-02-12 20:13                                     ` Tom Breton (Tehom)
2009-02-13  4:23                                       ` Manish
2009-02-12 20:55                                     ` Patch " Tom Breton (Tehom)
2009-02-13  4:38                                       ` Manish
2009-02-11  1:08                                 ` Tom Breton (Tehom)
2009-02-11 10:34                                   ` Carsten Dominik
2009-02-11 21:41                                     ` Tom Breton (Tehom)
2009-02-11 23:38                                       ` Nick Dokos
2009-02-12  4:17                                         ` Tom Breton (Tehom)
2009-02-11 23:44                                       ` Carsten Dominik
2009-02-12  4:27                                         ` Tom Breton (Tehom)
2009-02-12 15:49                                           ` Nick Dokos
2009-02-12 20:32                                             ` Tom Breton (Tehom)
2009-02-12 21:25                                               ` Nick Dokos
2009-02-11 12:29                                   ` Carsten Dominik
2009-02-11 14:58                                     ` Docs submitted Bernt Hansen
2009-02-11 17:33                                       ` Samuel Wales
2009-02-11 15:38                                     ` Docs submitted (Was Re: Advice sought on managing decision alternatives.) Daniel Clemente
2009-02-11 15:41                                       ` Carsten Dominik
2009-02-11 20:02                                     ` Tom Breton (Tehom)
2009-02-11 23:45                                       ` Carsten Dominik
2009-02-11  1:45                                 ` Slight fix to update-org.sh Tom Breton (Tehom)
2009-02-10 23:19                               ` Docs submitted (Was Re: Advice sought on managing decision alternatives.) Tom Breton (Tehom)
2009-02-11 10:34                                 ` Carsten Dominik
2009-02-10 22:45                             ` Tom Breton (Tehom)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1555.24.62.30.15.1234235653.squirrel@mail.panix.com \
    --to=tehom@panix.com \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).