Category Archives: org

Bugfix: Time estimation

This is a slightly better version of sacha/org-calculate-free-time that can understand prioritized tasks. Also, if you're working after midnight, it takes into account the need to sleep. That is, it doesn't treat _now_ as the starting point for the free-time calculation unless it's after the start time, so if you're up at 12:30 writing Emacs Lisp code, Emacs doesn't assume you've got 450 extra minutes of work time.

This is what the result looks like:

Wednesday 26 December 2007
   8:00......  --------------------
  10:00......  --------------------
  12:00......  --------------------
 Scheduled:  12:00-21:00  TODO Christmas festivities with W-'s family
  14:00......  --------------------
  16:00......  --------------------
  18:00......  --------------------
  20:00......  --------------------
  22:00......  --------------------
 Scheduled:               TODO [#A] 120 Write Planner and Org comparison for tasks
 Scheduled:               TODO 30 Start on my letter for 2007
 Scheduled:               TODO 60 Respond to e-mail
 Scheduled:               TODO 30 Donate when my charity budget hits $1000
 Scheduled:               WAITING 30 Send money to Ateneo CS dept
 In 919 d.:               101 things in 1001 days
90.0% load: 270 minutes to be scheduled, 300 minutes free, 30 minutes ga

And here's the code:

(defun sacha/org-agenda-load (match)
  "Can be included in `org-agenda-custom-commands'."
  (let ((inhibit-read-only t)
        (time (sacha/org-calculate-free-time
               ;; today
               (calendar-gregorian-from-absolute org-starting-day)
               ;; now if today AND after starting time, else start of day
               (if (= org-starting-day
                      (time-to-days (current-time)))
                    (let* ((now (decode-time))
                           (cur-hour (nth 2 now))
                           (cur-min (nth 1 now)))
                      (+ (* cur-hour 60) cur-min))
                    (let ((start (car (elt org-agenda-time-grid 2))))
                      (+ (* (/ start 100) 60) (% start 100))))
                 (let ((start (car (elt org-agenda-time-grid 2))))
                   (+ (* (/ start 100) 60) (% start 100))))
                 ;; until the last time in my time grid
               (let ((last (car (last (elt org-agenda-time-grid 2)))))
                 (+ (* (/ last 100) 60) (% last 100))))))
    (goto-char (point-max))
    (insert (format
             "%.1f%% load: %d minutes to be scheduled, %d minutes free, %d minutes gap"
             (/ (car time) (* .01 (cdr time)))
             (car time)
             (cdr time)
             (- (cdr time) (car time))))))

(defun sacha/org-calculate-free-time (date start-time end-of-day)
  "Return a cons cell of the form (TASK-TIME . FREE-TIME) for DATE, given START-TIME and END-OF-DAY.
DATE is a list of the form (MONTH DAY YEAR).
START-TIME and END-OF-DAY are the number of minutes past midnight."
  (let ((files org-agenda-files)
        (total-unscheduled 0)
        (total-gap 0)
        (last-timestamp start-time)
    (while (setq file (car files))
      (catch 'nextfile
        (org-check-agenda-file file)
        (setq rtn (org-agenda-get-day-entries file date :scheduled :timestamp))
        (setq rtnall (append rtnall rtn)))
      (setq files (cdr files)))
    ;; For each item on the list
    (while (setq entry (car rtnall))
      (let ((time (get-text-property 1 'time entry)))
         ((and time (string-match "\\([^-]+\\)-\\([^-]+\\)" time))
          (setq scheduled-entries (cons (cons
                                         (save-match-data (appt-convert-time (match-string 1 time)))
                                         (save-match-data (appt-convert-time (match-string 2 time))))
         ((and time
               (string-match "\\([^-]+\\)\\.+" time)
               (string-match "^[A-Z]+ \\(\\[#[A-Z]\\] \\)?\\([0-9]+\\)" (get-text-property 1 'txt entry)))
          (setq scheduled-entries
                (let ((start (and (string-match "\\([^-]+\\)\\.+" time)
                                 (appt-convert-time (match-string 2 time)))))
                  (cons (cons start
                              (and (string-match "^[A-Z]+ \\(\\[#[A-Z]\\] \\)?\\([0-9]+\\)" (get-text-property 1 'txt entry))
                                   (+ start (string-to-number (match-string 2 (get-text-property 1 'txt entry))))))
         ((string-match "^[A-Z]+ \\(\\[#[A-Z]\\] \\)?\\([0-9]+\\)" (get-text-property 1 'txt entry))
          (setq total-unscheduled (+ (string-to-number
                                      (match-string 2 (get-text-property 1 'txt entry)))
      (setq rtnall (cdr rtnall)))
    ;; Sort the scheduled entries by time
    (setq scheduled-entries (sort scheduled-entries (lambda (a b) (< (car a) (car b)))))

    (while scheduled-entries
      (let ((start (car (car scheduled-entries)))
            (end (cdr (car scheduled-entries))))
       ;; are we in the middle of this timeslot?
       ((and (>= last-timestamp start)
             (<= last-timestamp end))
        ;; move timestamp later, no change to time
        (setq last-timestamp end))
       ;; are we completely before this timeslot?
       ((< last-timestamp start)
        ;; add gap to total, skip to the end
        (setq total-gap (+ (- start last-timestamp) total-gap))
        (setq last-timestamp end)))
      (setq scheduled-entries (cdr scheduled-entries))))
    (if (< last-timestamp end-of-day)
        (setq total-gap (+ (- end-of-day last-timestamp) total-gap)))
    (cons total-unscheduled total-gap))))

On Technorati: ,

Random Emacs symbol: gnus-summary-display-while-building - Variable: If non-nil, show and update the summary buffer as it's being built.

Emacs: Choosing between Org and Planner

jaaronfarr asked me why I switched from Planner to Org. Both of them are popular personal information managers for Emacs, and both of them have practically all the features I need. They both do a good job at helping people manage tasks, schedule, and notes. If you have a few months to explore this, I suggest that you try both for at least a month each. On the other hand, if you want quick results, some time thinking about how you plan can save you more time later.

I tried out Org because I was working on a chapter about schedule management and it wasn't fair to just rely on the manual or the mailing list. In the beginning, I felt frustrated by the lack of things I'd gotten used to in Planner: the freedom to edit anything on my day page, little conveniences like +2tue to mean two Tuesdays from now (which Carsten has just added), publishing my blog...

After two months of using Org almost every day, I'm starting to understand it. I've come to appreciate the ease of working with an outline. I love the way it clocks time. I find the daily and weekly views really helpful. I've hacked stuff for it: time/load estimation, time reporting, next action summaries, agenda publishing... I'm fairly deeply

As a geek, I have to confess—I like Planner more. Planner is more fun to code. Maybe it's because I've spent years with it, and I know my way around the source.

Maybe it's because we split Planner up into lots of little pieces that can be reused and advised. Maybe the modularity of Planner is because chunks of the code were written on a computer with a teensy screen, which forced me to write functions that fit 80x48 characters. (See, that limitation was there for a reason!) There are plenty of entry points. From time to time, I still find myself copying an entire function in order to change something in the middle, but usually I can just get away with wrapping something around something else. With Org, I find myself doing a lot of copy-and-paste programming. I'd fix this by breaking the functions down into smaller bits, but I don't have the brainspace right now. Maybe after the book.

Org is better for my brain, though. It gives me a better overview of both the ground-level tasks (what am I going to do right now, today, this week) as well as the 50,000-foot view (what are my big projects)? Planner's good at the ground-level tasks, but the overview's always been a little awkward because it has to visit a number of files to get a big picture. Org handles that easily.

And the one-place-for-data thing of Org is pretty cool, too. Org dynamically generates reports, which could take a bit longer if you have a large Org file. Planner copies data wherever it makes sense, so you'd have a copy of the task on your day page and a copy of the task on your plan page. Plan pages can get out of sync unless you're either religious about using planner-edit-task-description and other functions to edit your tasks, or you use planner-id and you're lucky. Timeclock entries get out of sync, too. You can trust Org more than Planner in terms of consistency.

So now I'm kinda in the middle of these two modules. I use Org for all my work tasks, and I'm moving towards using it for all of my personal tasks as well. But I still keep my blog entries in Planner, even though they get mirrored into a WordPress blog on my web server.

*What would I recommend?*

It depends on the way you think. If you're the kind of person who was never happy with day planners because you needed more space to doodle, write notes, move things around, add other things, try out Planner. If you like outlines and organizing your tasks into projects, try out Org.

Note that just because you work that way now doesn't mean you'll work that way in the future. Don't worry. Emacs will adapt. You can switch between Planner and Org fairly easily. Just give yourself a week or so to adjust (or a month if you've customized your old tool extensively and miss lots of things about it). Use the tool every day, and you'll be fine.

Have you tried out both? Or have you tried out one of them and are curious about the other? I'd love to learn from your experience or answer your questions.

On Technorati: , , ,

Random Emacs symbol: malayalam-composition-function - Function: Compose Malayalam characters in REGION, or STRING if specified.

Emacs: Getting Things Done with Org – Basic

2(please remove leading spaces from code excerpts) You'd like to use the Org Mode for Emacs to manage your tasks. In this blog post, I'll cover the absolute minimum you need to get started. We'll assume that you already have GNU Emacs 22 and that you're reasonably familiar with using Emacs, including installing external modules and adding them to your load path. There are a million ways to plan, but we're going to focus on two. The first approach is Getting Things Done (GTD), described by David Allen in the book of the same title. GTD focuses on next actions (the very next thing you can do) and uses context lists to keep things manageable. Popular ways to do GTD are with index cards, recycled business cards, or software programs. If most of your tasks are in your head or scattered on scraps of paper, GTD will probably give you the most organizational bang for the least effort. The second approach is day planning. You plan your week based on your projects and priorities, write your tasks onto the pages for each day, and copy unfinished tasks over to the next day. If you've used one of those Filofax, Franklin-Covey or Dayrunner personal organizers, you're probably used to this way of planning. As you learn more about Emacs and task management, you'll probably develop your own way of doing things. These two are a good place to start, though. (Don't recognize how you plan your day, but interested in using Emacs anyway? Please get in touch with me! I may know of something that fits, and I'd certainly love to hear about the way you work.) If you use GTD, read on. Otherwise, read the Setup and then wait for the next blog post! =)

Set up

Org is part of Emacs 22. To make it even easier to collect tasks and notes, install a separate package called Remember. First, download and unpack Remember. As of this writing, Remember is at version 1.9. You can get the TAR.GZ from or the ZIP archive from . If these instructions are out of date, check to find out where to get Remember. Then add this basic configuration for Org and Remember to your ~/.emacs,

   (add-to-list 'load-path "~/elisp/remember-1.9")                                  ;; (1)
   (require 'remember-autoloads)
   (setq org-remember-templates
      '(("Tasks" ?t "* TODO %?\n  %i\n  %a" "~/")                      ;; (2)
        ("Appointments" ?a "* Appointment: %?\n%^T\n%i\n  %a" "~/")))
   (setq remember-annotation-functions '(org-remember-annotation))
   (setq remember-handler-functions '(org-remember-handler))
   (eval-after-load 'remember
     '(add-hook 'remember-mode-hook 'org-remember-apply-template))
   (global-set-key (kbd "C-c r") 'remember)                                         ;; (3)

   (require 'org)
   (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))                           ;; (4)
   (global-set-key (kbd "C-c a") 'org-agenda)                                       ;; (5)
   (setq org-todo-keywords '("TODO" "STARTED" "WAITING" "DONE"))                    ;; (6)
   (setq org-agenda-include-diary t)                                                ;; (7)
   (setq org-agenda-include-all-todo t)                                             ;; (8)
  • (1): Change the directory as necessary.
  • (2): You can use a different filename.
  • (3): You can change this keyboard shortcut.
  • (4): This tells Emacs to open all .org files in org-mode.
  • (5): You can change this keyboard shortcut.
  • (6): This makes it easy to pull in holidays and other events. See the chapter on managing your schedule.
  • (7): This includes all unfinished todos in the Org daily and weekly views. You can remove this line when you get used to working with todo lists.
After you evaluate that code by calling M-x eval-buffer or restarting Emacs, you're ready to create an Org file.
  1. Open ~/ (or whichever file you specified in (2)).
  2. Save it. This is probably the only time you'll have an empty TODO list.
  3. Use C-c [ (org-agenda-file-to-front) to add it to your org-agenda-files. You only need to do this once for this agenda file.
Read on to find out how to use your new Org file for GTD, or skip ahead to the section on Day Planning to find out how to plan by day!

Org and GTD

So you've read David Allen's book about Getting Things Done (or any of the countless summaries of it on the Net), and you'd like to get started with Emacs and Org mode. I'll show you the bare minimum you need to support the five phases in the GTD task workflow:

Phase GTD Org
Collect Capture everything you need to do. Collect all your bits of paper or put everything into your inbox
Process Actionable? Yes: do, delegate, or defer; no: file, throw, or incubate Put tasks on your list, track delegated tasks
Organize Next actions, projects, waiting for, someday/maybe Tag tasks, view tasks by tag
Review Daily, weekly, etc. Agenda view
Do Actually do the work! No, Emacs won't do the work for you... (But it can brew coffee!)
The first thing you need to do is get all the tasks out of your head, off scraps of paper, out of your e-mail, and so on. If this is the first time you're putting tasks into Org, you have a lot of tasks to collect. The best way to collect lots of tasks is to open your Org agenda file (~/ and put this heading at the end of the file:
   * Inbox
Now go to the end of the file, and type in ** TODO and the first task you can think of, like this:
   ** TODO Buy milk
Press C-M-RET and keep typing other tasks. Keep going until you've gone through all the things in your head and all the scraps of paper lying around. Do not get distracted. Your goal is to write all the tasks down. If you are as easily distracted as I am, do not even open up a browser window or look at your e-mail. It can be a real struggle sometimes to focus long enough to get everything down, especially when you're writing down all these tasks that you can work on. DO NOT DO A TASK UNLESS IT TAKES LESS THAN TWO MINUTES TO DO. In fact, if you are just starting out with GTD, you might find it better to resist all temptations to do tasks during this step. Get it all out. Now that you've gotten your tasks out of your head and into your file, breathe. There's less stress in your brain now, because you don't have to worry about forgetting things (as long as you remember to check your Org file, that is!). DO NOT FILL YOUR BRAIN BACK UP WITH OTHER THINGS TO DO. The brain is a wonderful thing, but it's not good at remembering what you need to do. Whenever a task comes your way—through e-mail, in conversation, in the shower—put it in your ~/ Well, you probably don't want to drip all over the computer, so sometimes you'll need to hang on to an idea—but get it out of your head and into your organizer as quickly as possible. To collect tasks within Emacs as they come up, use Remember. With the basic configuration you set up in the previous section, you can use C-c r t (or M-x remember and "t" for the Tasks template) to pop up a buffer where you can type in the task description and some notes.
    ## Filing location: Select interactively, default, or last used:
    ##     C-u C-c C-c  to select file and header location interactively.
    ##         C-c C-c  "~/notebook/personal/" -> "* Tasks"
    ## C-u C-u C-c C-c  "???" -> "* ???"
    ## To switch templates, use `M-x org-remember'.

    * TODO
And if you're lucky, there will even be a hyperlink to the file or e-mail you were looking at when you called C-c r t (remember, tasks). If you brain-dump your tasks and use C-c r t to collect tasks as they come up, you can free up your brain for other things, such as contemplating the meaning of life.
Now that you've collected all those tasks into your inbox, you can process them. Open your Org agenda file and go to your inbox. For every item there, decide if it's something that you need to act on. Is it really just a note? If so, take out the TODO keyword and organize it like you would store other notes. If it's a true-blue task, decide if it's something you can do within the next two minutes, delegate to someone else, or leave on your task list. Go through your list systematically, delegating and eliminating whenever possible. If you delegate the task, change it to WAITING by moving your cursor to the headline with the TODO keyword and typing S-r (org-shiftright) until it changes to WAITING. To keep track of who you delegated it to, just edit the task description to reflect it. Your organizer file will look like this:
 ** WAITING Buy milk - WJY
You have a list of tasks that _you_ need to act on. If you've braindumped everything that people have asked you to do and that you've thought of doing, this is probably a very long list. Intimidatingly long. The next step in restoring sanity to your life is to organize your list into next actions, projects, things you're waiting for, and someday/maybe tasks. Review that task list. For each task, decide if it's something you can do immediately. Is it something you can do in one sitting, and do you have everything you need in order to do it? If so, great! It's a next action. Leave it on your task list. If you can't immediately work on a task, it may be a project in disguise, and it needs to be broken down into smaller, concrete next actions. For example, the task:
 ** TODO Write a book about Emacs
would probably result in me getting complete writer's block. If you're faced with a big task like this, move it out of your inbox and make it a project. Then you can think of the very next action you need to do. Your Org file could look something like this:
 * Projects

 ** Emacs book
 *** TODO Write about basic Org and GTD

 * Inbox

 ** TODO ... lots of other things go here ...
 ** TODO ... lots of other things go here ...
 ** TODO ... lots of other things go here ...
A task might also be stuck because you need to wait for someone else. For example, I'm currently working on renewing my visa, but I need to wait for the embassy. Mark those stuck tasks as WAITING with S-right (org-shiftright). Someday/maybe tasks are nice to think about once in a while, but you don't want to clutter your day-to-day tasks with them. A basic way to deal with this is to move those tasks into a separate Organizer file such as ~/ . Another is to use tags, which we'll cover in the section on intermediate Org. For now, just move them to another file.
You've gone from a whole bunch of tasks in your brain and on pieces of paper to one text file containing everything you need to do, with an easy way to get to just the things you can do right now. To view all your tasks, type C-c a t (org-agenda, tasks). You'll get something that looks like this:
  Global list of TODO items of type: ALL
  Available with `N r': (0)ALL (1)TODO (2)STARTED (3)WAITING (4)DONE
  TODO Write about basic Org and GTD
  TODO Blog
  TODO Answer my mail
  TODO Alter slacks
Type "1 r" to show only the active tasks, and review what you're waiting for with "3 r". Review this WAITING list every so often to make sure that nothing falls through the cracks. Type "f" to start follow mode, which displays the relevant lines from your Org agenda file as you move around. This is helpful for quickly reviewing your task list.
All of the above should take you less than fifteen minutes of planning each day. The rest of the time, you can focus on doing the work, undistracted by shiny new tasks that pop up because you can get them out of your way with C-c r t. To work, review your task list with either C-c a t (org-agenda, tasks) or C-a a (org-agenda, agenda). From the agenda view, type "t" (org-agenda-todo) to change the task status. I find it helpful to mark a task as STARTED because it helps me remember what I was working on in case I get distracted by something urgent, but you can also use C-u t to jump to a status without cycling through the ones in between (say, marking a task as DONE). You can also press ENTER to jump to the task headline and edit it directly. Going back to reviews: As you mark tasks done, you'll also want to do daily and weekly reviews. You can see those with C-c a a (org-agenda, org-agenda-list), which opens an Org agenda view. To see completed tasks in the Org agenda view, type l (org-agenda-log-mode). To switch to the day view, type d (org-agenda-day-view). To switch to the week view, type w (org-agenda-week-view). The basic configuration I've suggested here will automatically include unfinished tasks at the beginning of the agenda. Scroll up to review your tasks, and press ENTER on a line to jump to it.
Wrapping up
There's a lot more you can do with Org to make it support GTD, but here's a basic configuration that can get you started on collecting, processing, organizing, managing, and actually doing your tasks. Stay tuned for the intermediate Org article for more tips on setting up repeated tasks, clocking time, working with projects, and tagging tasks! On Technorati: , , , Random Emacs symbol: bbdb-edit-current-field - Command: Edit the contents of the Insidious Big Brother Database field displayed on UPDATE: Thanks, Victor, for catching the bug! Changed org-install to org.

How to use Emacs Org as a Basic Day Planner

So you want to use Org as day planner. I'll show you the bare minimum that you need in order to use Org to manage your tasks day by day. I assume that you've set up Org and Remember according to the basic configuration suggested in "Setup." If you haven't done that yet, please review the section on "Setup", then return here.

Here's what you'll learn how to do:

  1. Collect your tasks
  2. Schedule the tasks for specific days
  3. View your daily or weekly agenda
  4. Mark tasks as done
  5. Reschedule a task
  6. Review your accomplishments

Collecting your tasks

If you're adding many tasks, you may find it easier to edit your Organizer file. Open ~/ in Emacs and go to the end of the file. Add headlines like this:

 * Inbox
 ** TODO your task description here
 ** TODO another task...

Instead of typing ** TODO again and again, you can use C-M-RET to create another TODO heading at the same level as the previous one. Think of all the things you need to do over the next few days and add them to your Org agenda file.

More tasks will come up as you work on things. Instead of switching to your Org agenda file each time you need to add a task, you can use C-c r t (remember, Tasks template) to remember the task quickly. Try it now by typing C-c r t. Type in the task description and press C-c C-c (org-ctrl-c-ctrl-c) to add the task to the end of the ~/ file.

Now you have plenty of tasks on your list, but no idea when you need to do that. Here's where scheduling and deadlines come in.

Scheduling tasks

To schedule a task, move your cursor to the TODO headline and press C-c C-s (org-schedule). Org will prompt you for a date. It understands full, partial, and relative dates. For example, if today is December 29, 2007, then It understands any of the following:

Input Result Explanation
(blank) 2007-12-30 Today
10:30 2007-12-30 10:30 Time today
3:30pm 2007-12-30 15:30 Time today
31 2007-12-31 Day in the current month
12-31 2007-12-31 Month and day in the current year
2008-01-01 2008-01-01 Date
2008-01-01 12:30am 2008-01-01 00:30 Date and time (also works with partial dates)
+2 2008-12-31 Two days from now
-3 2007-12-26 Three days ago
Fri 2008-01-04 The nearest Friday (on or after today)
+2w 2008-01-12 Two weeks from today

To set a deadline for a task, type C-c C-d (org-deadline). It accepts the same kinds of date that org-schedule does.

Try this out by scheduling all of your tasks over the next few days, adding deadlines where necessary.

Now that you've added date information to your tasks, you probably want to see those tasks organized by date instead of in the random way you entered them. Agenda views are going to become your new best friend.

Viewing your daily or weekly agenda

Type C-c a a (org-agenda, org-agenda-list) to view your agenda. By default, Org shows a weekly view of your scheduled tasks and appointments. This is your Org agenda view.

Here are some useful navigational keys:

  • Switch to a daily view with d (org-agenda-day-view)
  • Switch to a weekly view with w (org-agenda-week-view)
  • View earlier or later days/weeks with your left and right arrow keys (org-agenda-earlier, org-agenda-later)
  • Jump to a specific day with j (org-agenda-goto-date)

Get into the habit of typing C-c a a to check your task list. It may also help to add


to the bottom of your ~/.emacs. This opens your Org agenda view when you start up Emacs. Start your Emacs day with your Org agenda, check it every time you finish a task, and review it before you end the day. This will help you make sure that nothing falls through the cracks.

Marking tasks as done

The easiest way to mark a task as done is to go to its line in your Org agenda view. Type C-c a a (org-agenda, org-agenda-list) to view your tasks for today, move your cursor to the task, and type t (org-agenda-todo) to cycle the task status until it's marked DONE. You can also type C-u t (org-agenda-todo with a prefix argument) to jump to a specific task status. For example, you could type C-u t DONE to mark a task as done.

You can also mark tasks done from your ~/ file. Open the file and move your cursor to the item. Type C-c C-t (org-todo) to change the task status. Again, you can type C-u C-c C-t (org-todo) to jump to a specific task status.

I find it helpful to mark tasks as STARTED when I start working on them, WAITING if I need something else in order to continue working on the task, and DONE when I'm finished with it. That way, I can quickly see which task I was supposed to be working on before I got distracted by something bright and shiny, and I can also see what I'm waiting for. Get into the habit of doing that, and you'll find it easier to get back on track after distractions.

Unfortunately, Org does not come with a M-x org-zap-distractions command. There will be days when you can't do everything on your task list.

Rescheduling Tasks

You don't have to reschedule your tasks. Org will remind you of unfinished, scheduled tasks every single day. It will even helpfully tell you how many days you've procrastinated on that task. If you use C-c a a (org-agenda, org-agenda-list) when you have unfinished tasks on previous days, you'll see task reminders like this:

Saturday  29 December 2007
  organizer: Scheduled:  TODO Respond to mail
  organizer: Sched. 6x:  TODO Write notes from mentoring conversation
  organizer: Sched. 2x:  WAITING Report time

You could let your unfinished tasks snowball on you in a big mass of procrastination. If you let your task list grow to an intimidating size, though, you may start stressing out about the things you aren't doing. Let me show you how to procrastinate—I mean, reschedule your tasks effectively—so that you can work with a more manageable task list.

If tasks are starting to accumulate, it's a good sign that you need to review those tasks. Do you really need to do them? If not, delete them by moving to the line in your Org agenda view and pressing C-k (org-agenda-kill). You can also edit your ~/ file and delete them, but org-agenda-kill is more convenient.

If you really need to do the tasks, but there's no point in seeing it in today's task list because you can't do it today anyway, use C-c C-s (org-agenda-schedule) to reschedule the task. If you're only moving it a couple of days ahead, use S-right (org-agenda-later) to move it forward, and S-left (org-agenda-earlier) if you overshoot.

Some tasks show up again and again on your task list, and you know you need to do them, but you don't know where to getting started. "TODO Write a book" is not a good task, because it's just too big to do in one sitting and it doesn't tell you what to do right now. Big tasks are often projects in disguise. Break it down into smaller tasks, and schedule those instead. If you're in the Org agenda view, press RET (org-agenda-switch-to) to jump to the task in your ~/ file. Break it down into smaller tasks by adding sub-headings and more TODOs, like this:

 ** Write a book
 *** TODO Make an outline of what to write
 *** TODO Read sample query letters
 *** TODO Write a query letter
... and so on.

Then you can use C-c C-s (org-schedule) to schedule those tasks.

Use these commands to keep your task list manageable. That way, you get the warm and fuzzy feeling of accomplishment when you finish what's on your list and you look at everything you've done today.

Reviewing your accomplishments

If you've been good about keeping your tasks in your ~/ file, working with your Org agenda view, and marking tasks as DONE when you finish them, you'll find it easy (and satisfying!) to review your accomplishments. Just open your daily or weekly Org agenda view with C-c a a (org-agenda, org-agenda-list). Type l (org-agenda-log-mode) to show completed tasks. Pat yourself on the back, then plan yourself another wonderful day tomorrow!

On Technorati: , ,

Random Emacs symbol: set-fill-column - Command: Set `fill-column' to specified argument.

Clocking Time with Emacs Org

2Many professionals bill clients for their time. Even if you don't, keeping track of the time you actually spend on tasks can help you improve your time estimates and check if you're spending enough time on the things that are important to you. For example, keeping track of the time you spend on tasks might show you that you spend two and a half hours each day just responding to e-mail. If you can identify problem areas like that, then you can look for more effective ways to perform the tasks that take up a lot of your time. I love Org's timeclocking support, and I think you will too. Because it's integrated with your task list, you don't have to switch to separate application or reenter data. You can get more detailed time reports, too. All you have to do is remember to clock in before you start a task and clock out when you finish it.

Starting and stopping the clock

You can clock in by moving your cursor to the task headline in either your file or the org agenda view, and then pressing C-c C-x C-i (org-agenda-clock-in or org-clock-in, depending on context). This adds the time stamp to the task. If you are already clocked into another task in that organizer file, you'll be clocked out of it to prevent you from accidentally double-billing.

To clock out of a task, type C-c C-x C-o from the task headline. Marking a task as done will also automatically stop the clock, if that was the task with the active clock. Here's some code to make this even easier. The following code clocks in whenever you market task is started, and clocks out when you market a task as WAITING. It also automatically market task is started if you clock in. This takes advantage of the Org configuration previously suggested in the Setup section. Add this to your ~/.emacs and evaluate it:
(eval-after-load 'org
     (defun wicked/org-clock-in-if-starting ()
       "Clock in when the task is marked STARTED."
       (when (and (string= state "STARTED")
		  (not (string= last-state state)))
     (add-hook 'org-after-todo-state-change-hook
     (defadvice org-clock-in (after wicked activate)
      "Set this task's status to 'STARTED'."
      (org-todo "STARTED"))
    (defun wicked/org-clock-out-if-waiting ()
      "Clock out when the task is marked WAITING."
      (when (and (string= state "WAITING")
                 (equal (marker-buffer org-clock-marker) (current-buffer))
                 (< (point) org-clock-marker)
	         (> (save-excursion (outline-next-heading) (point))
		 (not (string= last-state state)))
    (add-hook 'org-after-todo-state-change-hook
What if you forgot to clock into a task when you started? No problem. Simply clock in and out of it, then edit the starting timestamp for the task in your ~/ file. To find a starting timestamp, move your cursor to the task headline. If the task has been collapsed to a single line, press TAB to expand it. Look for a line that starts with CLOCK:, or a collapsed segment that starts with :CLOCK:. If you see a collapsed segment, he expanded by moving a cursor to it and pressing tab. Find the clock entry you want to change, and if the timestamp, and press C-c C-y (org-evaluate-time-range) to update the time total.

Reporting time

By project
To see how much time you've spent on a project or task, open your ~/ file and press C-c C-x C-d (org-clock-display). Total times will be added to each headline, summarizing the times for each subtree. You can also use one of Org's dynamic blocks. Open your ~/ file, move your cursor to where you want the report inserted, and type C-c C-x C-r (org-clock-report). By default, the reports will include all the second-level headings for all the days. What if you want to limit the report to just the time you clocked last week?
Reporting time for a period
To summarize it for a span of days, change the starting line from:
#+BEGIN: clocktable :maxlevel 2 :emphasize nil
to something like:
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :tstart "<2007-12-25 Sun>" :tend "<2007-12-31 Mon>"
where tstart is the starting time/date and tend is the ending time/date. You can add the timestamps either manually or with C-c C-. (org-time-stamp). After you change the block definition, update the clock table by typing C-c C-x C-u (org-dblock-update). You can also use a definition like:
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :block today
to see today's entries. Other block keywords are 'yesterday', 'thisweek', 'lastweek', 'thismonth', 'lastmonth', 'thisyear', or 'lastyear'. If you need more levels of headings, change the value of maxlevel. For example, to see a detailed clock table with up to 10 levels of headings, use
#+BEGIN: clocktable :maxlevel 10 :emphasize nil :block today
clocktable summarizes the reported time. What if you want the time broken down by day?
Reporting time by days
The following code creates a custom dynamic block that breaks the reported time by date. Add the following code to your ~/.emacs:
(defun org-dblock-write:rangereport (params)
  "Display day-by-day time reports."
  (let* ((ts (plist-get params :tstart))
         (te (plist-get params :tend))
         (start (time-to-seconds
                 (apply 'encode-time (org-parse-time-string ts))))
         (end (time-to-seconds
               (apply 'encode-time (org-parse-time-string te))))
    (setq params (plist-put params :tstart nil))
    (setq params (plist-put params :end nil))
    (while (<= start end)
        (insert "\n\n"
                (format-time-string (car org-time-stamp-formats)
                                    (seconds-to-time start))
           (format-time-string (car org-time-stamp-formats)
                               (seconds-to-time start)))
          (format-time-string (car org-time-stamp-formats)
                              (seconds-to-time end))))
        (setq start (+ 86400 start))))))
After you load that code, you'll be able to use a dynamic block of the form
#+BEGIN: rangereport :maxlevel 2 :tstart "<2007-12-25 Tue>" :tend "<2007-12-30 Sun>"
to see your time reported by date. Fill it in by moving your cursor within the block and typing C-c C-x C-u (org-dblock-update). Org makes it easy to capture timeclock information by integrating the timeclock into your task list so that you don't even have to think about it, and it can report this time by project or by date. You can use this information to bill clients, improve your time estimates, or reflect on the way you do things. All you have to do is clock in by marking a task as STARTED, and clock out by marking a task as WAITING or DONE. Don't get discouraged if the time clock shows you do only a few hours of productive work each day. Use that to help you figure out how to do to things better! On Technorati: , , Random Emacs symbol: term-previous-matching-input-string - Function: Return the string matching REGEXP ARG places along the input ring.

Projects in Emacs Org


Organizing your tasks into projects can help you plan ahead, track your progress, and stay motivated. Working from a project list allows you to plan your day or week instead of just reacting to other people's requests. Keeping your projects and tasks in Org makes it easier for you to review your completed tasks and plan the next step. If you include some text describing why you want to do the project and what your intended outcome is, this can help you stay motivated throughout a long project.

Projects can take a single day or several years. They can be large projects involving lots of other people and resources, or small projects that you do on your own. Projects may involve a handful of separate steps or a hundred things you need to do in order to achieve your goal. The important thing is that there is more than one step. If you organize your task list so that related tasks are together, then you'll find it easier to get a sense of where you are, where you're going, and what you need to do next.

In this section, you will learn how to:

  • Create projects,
  • Organize your tasks into projects,
  • Review your ongoing projects, and
  • Mark projects as finished.

I'll assume that you're using Emacs 22, and that you've set up Org using an ~/ agenda file and the basic configuration suggested in either "Org and GTD" or "Org as a Day Planner." I'll also assume that you're familiar with switching between the Org agenda view and the Org organizer file, and that you're comfortable navigating around Emacs.

The examples I'll use focus on yearly goals. You might also have short-term projects or long-term plans. Feel free to adapt the examples as needed.

Open your ~/ file. If you've collected your tasks as suggested in the previous sections on Using Org as a Day Planner or Using Org for GTD, your ~/ file might look something like this:

 * Inbox
 ** TODO Read Emacs Lisp intro
 ** TODO Write yearly review
 ** TODO Exercise
 ** TODO Browse the Emacs Wiki

Create new top-level headings for this year's goals or the projects that you're working on. You can create a top-level heading by typing * and the heading, like this:

 * Learn more about Emacs
 * Go on vacation
 * Inbox
 ** TODO Read Emacs manual

It's a good idea to add the projects to the beginning of the file (before your Inbox) because M-x remember adds new tasks or notes to the end of the file. If the last major heading as * Inbox, then the tasks and notes are automatically added to it. If the last major heading is a project, the tasks and notes may get misfiled.

What are your projects?
Yearly goals? I've got twenty-year plans!

If you're a top-down planner, you'll find it easy to list your projects. In fact, you might have a ten- or even twenty-year plan already written down. You'll find this section straightforward, because you're already used to planning in terms of projects. Go ahead and adapt the examples to your long-term plans.

Yearly goals? I live day by day!

If you're a bottom-up planner, you might be giving me a weird look right now. "Yearly goals? I'm lucky if I can figure out how to get through the next day!" This section will also show you how to find the recurring themes in your task list and organize them into projects. Give project-based planning a try for a month. If this way of thinking doesn't work for you, Org will work just fine without projects.

You probably have projects, even if you can't think of any right now. Review your ~/ file. If you haven't written down everything you needed to do yet, go through the section on basic configuration for your planning style (GTD or day planning). Once you have a list of things to do, you can then review it for big tasks, related tasks, and other project clues.

Read your tasks and ask yourself the following questions:

  • *Can I do this in one sitting?* Big tasks such as "Write a book" are often projects in disguise. Use projects so that you can break them down into smaller, doable tasks.
  • *Is this related to other tasks?* Related tasks such as "Book a flight" and "Plan my itinerary" are often clues to a project like "Go on vacation". Use projects so that you can review related tasks together.
  • *Why am I doing this?* When you think about the reason why you're doing something, you'll often find a bigger project. For example, if one of your tasks is "Set up an automatic retirement savings plan", then the question "Why am I doing this?" may lead you to the project "Plan for retirement". Use projects to help you think of other ways to move towards that goal.

Big tasks need to be broken down into smaller tasks anyway, and organizing them into projects will help you make them more manageable. You may not want to organize all of your other tasks into projects. If you can pick some major themes to focus on, though, then you'll be able to see how the different things you do are related to each other, and you'll be able to think of other ways to work on those projects. If you're starting out with project-based thinking, maybe you can pick three to five projects and try to do a little work on each of them every day.

If you still don't identify any projects, that's okay. You can use Org as a straightforward task list. Jump ahead to the section on "Tags", as you'll probably find that useful.

On the other hand, if this step turns up plenty of projects, resist the temptation to over-correct and end up with hundreds of projects. I find that more than 7 active projects gets hard to manage. Pick a few main themes that you'd like to work on, and make everthing else something you plan to do someday.

Project tasks

Creating tasks

Now that you have project headings, think of the next thing you need to do in order to move those projects forward. If you've already written down those tasks, move them under the appropriate project heading. If not, type them in.

In order for a task to belong to a project, it needs to be under the heading and at a lower level. For example, if your project heading has one star, like this:

 * Learn Emacs

then your TODO headings should have two stars, like this:

 * Learn Emacs
 ** TODO Read the Emacs manual
 ** TODO Read the Emacs Lisp Intro manual (eintr)
 ** TODO Install the Emacs source code

If your tasks are not at the right level, you can add the star manually by editing the heading. You can also use M-right and M-left (org-metaright and org-metaleft) while on a heading in order to promote or demote it, and you can use M-S-right and M-S-left (org-shift-metaright and org-shift-metaleft) to promote or demote entire subtrees.

To move tasks up and down within the project, you can copy and paste the text. You can use M-Up and M-Down (org-metaup and org-metadown) to move subtrees.

Think of tasks you can do within the next week in order to move each of your projects forward. Add next actions to all of your active projects. Creating next actions for each of your projects makes it easier to remember to keep moving forward.

Organizing tasks

If you have many tasks in a project, you may want to organize them into sub-projects. For example, you might divide a software project into components. If you're starting from scratch, you can create the project structure by typing in more stars for sub-project headings. For example:

 * Learn Emacs
 ** Read mail
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message
 ** Browse the Web
 *** Read through the w3m documentation

You can also demote an existing project into a subproject. Use M-S-right (org-shift-metaright) on the current project headline in order to demote it to a sub-project. This will also demote the tasks within the project. For example, demoting this:

 * Learn Emacs
 ** TODO Choose a mail client
 ** TODO Install and configure the mail client
 ** TODO Send a message

will result in this:

 ** Learn Emacs
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message

Then you can change the heading and add another heading above it, like this:

 * Learn Emacs
 ** Read mail
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message

This kind of organization is optional, but it can help you get an idea of the overall structure of your project. Using different levels allows you to hide and show groups of headings by pressing TAB on the heading.

Now that you've created your project tasks and organized them the way you want, it's time to actually do the work.

Working on tasks

If you use Org as a day planner, you may also want to schedule the tasks onto specific days with C-c C-s (org-schedule). You can review your daily or weekly agenda with C-c a a (org-agenda, org-agenda-list), switching between daily and weekly views with d and w (org-agenda-day-view and org-agenda-week-view).

You can work with the next actions in the same way you work with other tasks, rescheduling them or marking them as STARTED, WAITING or DONE with the keyboar shortcuts introduced in the previous section on Org and GTD or Org as a Day Planner.

When you finish a project task, think of the next action you can do in order to move that project forward. If you use Org as a day planner, schedule the next action onto your calendar as well.

Reviewing projects

You can review your projects by opening your ~/ and browsing through the headings. S-tab (org-shifttab) changes the visibility of headings, so you can see just the top-level headings or all the details. You can use TAB (org-cycle) on a headline to show or hide subtrees.

Reviewing a list of projects

If you have many projects, you'll want a shorter view of just your active projects. To make it easier to review projects, add a PROJECT tag to all your active project headlines. You can add a tag by editing your ~/ and moving your cursor to the headline and typing C-c C-c (org-ctrl-c-ctrl-c), followed by the name of the tag (PROJECT). You can also manually type :TAGNAME: at the end of the headings, like this:

 * Learn more about Emacs        :PROJECT:
 ** TODO Read the Emacs manual
 ** TODO Read the Emacs Lisp Intro manual (eintr)
 * Go on vacation                :PROJECT:
 * Inbox

You might classify some of your projects as someday/maybe - things that are nice to think about, but which you aren't acting on right now. Tag your inactive or someday/maybe projects with PROJECT and MAYBE. If you're editing the ~/ file, just add :PROJECT:MAYBE: to the heading. If you're tagging it with C-c C-c (org-ctrl-c-ctrl-c), specify PROJECT:MAYBE as the tag.

 * Learn more about Emacs        :PROJECT:
 * Go on vacation                :PROJECT:MAYBE:
 * Inbox
 ** TODO Read Emacs manual

Now that you've tagged your projects, you can view just your project headlines with a custom agenda command. Custom agenda views are a terrific feature in Org, and you can do a lot with them if you know a little Emacs Lisp. Here's what you need to add to your ~/.emacs in order to get a list of your active projects and your someday/maybe projects:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)  ;; (1)
        ("m" tags "PROJECT&MAYBE" nil)       ;; (2)
        ;; ... put your other custom commands here
  • (1) This makes C-c a p (org-agenda, p) show your active projects.
  • (2) This makes C-c a m (org-agenda, m) show your "maybe" projects.

With these two commands, you can quickly review your active and inactive projects. To jump to a project from the agenda view, move your cursor to the heading and press RET (org-agenda-switch-to). If you want to scan through the projects quickly, use f (org-agenda-follow-mode) in the agenda view to turn on follow mode, then move to different headlines. Another window will show the headline at point.

If you review your projects at least once a week, you'll find it easier to make regular progress. If you want to combine your weekly/daily review with your project list, you can do that with org-agenda-custom-commands as well. Here's what you'd put in your ~/.emacs:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)
        ("m" tags "PROJECT&MAYBE" nil)
        ("a" "My agenda"                            ;; (1)
         ((org-agenda-list)                         ;; (2)
          (tags "PROJECT-MAYBE-DONE")))             ;; (3)
        ;; ... put your other custom commands here
  • (1) The first argument is the shortcut key, the second is a name for the agenda view
  • (2) Your daily or weekly agenda. The d and w (org-agenda-day-view and org-agenda-week-view) shortcuts work if the point is within this section
  • (3) A list of your active projects

This configures C-c a a (org-agenda, "My agenda") to display your agenda and a list of your project headings. Again, you can press RET (org-agenda-switch-to) to jump to a project from its heading in the agenda view.

Reviewing your stuck projects

You might have forgotten to create next actions for some of your active projects. Org can help you find projects which don't have next actions. You can then decide if the project is complete or if it needs further action.

To list stuck projects, you first need to tell Org what a stuck project is. The following code defines a stuck project as an active project (not tagged "maybe" or "done") that doesn't have a TODO or STARTED action, if the body of the project doesn't contain "*lt;IGNORE>". Add this to your ~/.emacs and evaluate it:

(setq org-stuck-projects
      '("+PROJECT/-MAYBE-DONE" ("TODO" "STARTED") nil "\\<IGNORE\\>"))

Then you can use M-x org-agenda-list-stuck-projects or C-a a # (org-agenda, org-agenda-list-stuck-projects) to show only the stuck projects. Review this list and jump to the headlines.

Want to add that to your custom agenda view? Modify the org-agenda-custom-commands value in your ~/.emacs to be like this:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)
        ("m" tags "PROJECT&MAYBE" nil)
        ("a" "My agenda"
          (org-agenda-list-stuck-projects)          ;; (1)
          (tags "PROJECT-MAYBE-DONE")))
        ;; ... put your other custom commands here
  • (1) It's a good idea to put it before your regular project list so that you can see what needs your attention.

What about finished projects? You might want to keep them in your Org file, but they shouldn't show up in your active and inactive project lists. Org can keep track of those projects too.

Marking projects as done

If you look at the custom commands above, you'll notice the "-DONE" specifier. "DONE" is the tag we'll use to indicate done projects. To tag a project as done, move the point to the project heading and type C-c C-c (org-ctrl-c-ctrl-c). The tag prompt will default to the current tags. Just add "DONE" and press Enter. With the custom commands we've set up, projects tagged DONE will not show in your active, inactive, or stuck project lists.

You can also add the tag manually. For example, if the project heading is

 * Learn Emacs    :PROJECT:

and you're happy with your level of Emacs proficiency, then you can mark it as done by changing it to

 * Learn Emacs    :PROJECT:DONE:

If you have plenty of completed projects, your Org file might be quite large. You can mark a subtree for archiving by typing C-c C-x C-a (org-toggle-archive-tag). This hides it from most Org commands. You can also archive a tree into a different file with C-c C-x C-s (org-advertized-archive-subtree).

Wrapping up

Now you can create projects, manage your project tasks, and review your active, inactive, and stuck projects in Org. You know how to mark projects as completed and how to archive them. You've also started using tags to dynamically generate reports from your Org file.

Tags can do a lot more. To find out what else you can do with tags, read the next section on "Tagging in Org".

On Technorati: , ,