Task-mode 0.8

Task-mode is a global minor mode which enables you to effectively do many tasks in the same time. This manual's purpose is to teach you how to use it.

WARNING: Although task-mode is already usable, it is not finished yet. Be warned: I disclaim all responsability for the loss of your work. Even if I think it is becoming stable, if you think you're stuck, there is a chance that C-z Q may save your life.

1. Installation notes

You have to put the file task.el in your load-path (for instance `/usr/share/emacs21/site-lisp'), then put (require 'task) in your `.emacs'. Put (task-mode) in your `.emacs' if you want task-mode to be permanently activated, else use M-x task-mode.

2. Overview

Task-mode is a global minor mode for emacs which can automatically manage the window configurations for you. It enables you to group your buffer into tasks, and provide practical means to switch between tasks, to add buffers to task, to manage buffers and window configurations into tasks. Although it can seems difficult to use, it isn't, so please try the tutorial (see section 3. Getting Started), and you should quickly become familiar with the 4. Concepts.

2.1 Features

Here is some of the features currently in task-mode:

• Practical switching beetween tasks: You can switch task just by switching buffer, or explicitly tell to go to a task C-z g.
• You can switch easily among the buffers in a task, using an interactive switch limited to the buffers of the task.
• (still beta) Per-task window configuration ring, which does in tasks what See section `Winner mode' in The GNU Emacs Manual. does to frames. You can configure it very accurately.
• Task management can be done automatically, either by specifying rules for belonging of buffers in task, either by adding them automatically when you create new buffers. You can quickly add or remove several buffers in one task interactively by editing its rules.

2.2 Coming soon

I have a TODO list of more than a hundred lines, but here's some of the main features that should be added one day:

• Possibility to merge two tasks, and define a merge of task in the task rules.
• Interaction between tasks and frame: one-task-per-frame mode, defining frame in rules and automatically create them, and of course frames should be raised when we switch to a task it contains.
• Better handling of killing buffer, with the possibility to delete windows when it' smart to do so, etc
• And many more...

Feel free to send me feature requests! Please tell me if you plan to implement something, so that we can coordinate our work.

2.3 Known problems

• You can't launch task-mode twice.
• You must set the task-properties before launching task-mode.
• The documentation isn't well formatted, nor has links, nor is complete.
• Switching task does not save point.

They are beeing treated and will soon be corrected.

3. Getting Started

This chapter will introduce you to the concepts of task-mode. You will learn how to use it and the important keybindings.

3.1 Task switching

Open a new emacs session, load task-mode (M-x load-file RET task.el) and launch task-mode (M-x task-mode)

You should be in front of the *scratch* buffer. You should be able to see a little [Misc] in the modeline. This is the name of the default task.

Open a new buffer, name it a. You can still see the [Misc] in the mode line: newly created buffers are normally added to the current task.

Then create a new task C-z c. Name it "test", for instance.

You should notice that now, a's current task is [test].

Split your screen in two , so that you'll be able to see the window configurations change.

You can quickly switch beetween the two last tasks using C-z C-z (task-quick-switch). Try it now, you're back to [Misc].

Now, switch back to buffer a, with C-x b for instance. You're back to your double-windowed screen. Notice that switching task by switching buffers is not done by rebounding C-x b, so you can use any mean to switch between buffers and it will work. (for instance, C-c C-spc which brings you to an ERC buffer will also work, M-x man also, etc...)

Switch to buffer *scratch*. Notice that you don't switch to [Misc]. This is because [Misc] is flying by default.

The third way to switch between task is using task-goto (C-z g). Now type C-z g RET to return to [Misc].

To see how it can be useful, just create a new buffer foo, and then create another task [bar]. Then try switching beetween a and foo a few times. Try some C-z C-z too.

OK now open a new buffer b in task [test]. Switch to task [bar], and then switch to buffer a. a should be selected in task [test]. Open a buffer c, switch to [bar] and switch to a: a is displayed in the last selected window.

If it does not please you, you can use C-z p to switch back to the previous window-configuration, and then place a where you want.

3.2 Moving buffers beetween tasks

Now, imagine that finally, buffer c should go in task [bar]. There are three ways to do it:

• In task [bar], use task-add-buffer-to-current-task (C-z b), and type c RET.

• In task [test], go on a window which display buffer c and use task-move-current-buffer-to-task (C-z m), and type test RET.

• In any task, any buffer selected, use task-move-buffer-to-task , type in the name of the buffer you want to add, and then the name of the task (so type foo, then [test]).

Try to play a little with these command. They can occasionnaly be useful if you have mistaken when opening a new buffer. But now you must be thinking, "Hey what pain would it be to select all these buffers, one by one, to place them in the good tasks!". Fortunately, a powerful mechanism is here to do this for you: 3.3 The task rules.

3.3 The task rules

The task rules is the mechanism that will enable you to:

1. Move several buffers at one time to a task,
2. Place newly opened buffers in the good task automatically.

Create a new task [ruletest], and use task-edit-rules (C-z e). Use "." as the new rule. Your buffers "a", "b" and "c" should have been added to your new task!

Now switch to any task, and open any one character buffer. The newly created buffer should belong to to [ruletest].

You can also match major modes and directories.

For a complete enumeration and further explaination on the task rules, see 5.1 Customizing tasks.

If you want that your new buffers are automatically added to the good tasks, you should definitely customize (see section 5. Customization) your set of task and task rules.

3.4 Using task-mode

Now you should take a look in the 5. Customization. In this chapter is included several initial configurations that will help you use task-mode the way you want, and optimize its use.

4. Concepts

4.1 Tasks and buffers

There is nothing in this section for the moment, please go and see 3. Getting Started.

4.1.1 Creating tasks

4.1.2 Adding buffers to tasks

4.1.3 Switching beetween tasks

4.1.4 Killing tasks

4.1.5 Changing buffers from tasks

4.1.6 Rules

Information is provided here (see section 3.3 The task rules) and here (see section 5.1 Customizing tasks).

4.2 Flying tasks and buffers

Flying tasks are tasks for which switching to one of its buffer does not switch to task. Flying buffers are buffers in the flying tasks.

Buffer such as *Completion* for instance should always be flying.

See 5. Customization for seeing example of tasks that should be or should not be flying.

4.3 The Window configuration ring

It is working but not very well, so please don't use it for know.

5. Customization

You can use M-x customize-group RET task RET to customize task-mode.

5.1 Customizing tasks

The default rules are stored in an association list named task-properties.

For each task symbol, you have to associate a list which has the following structure:

(KEY1 VALUE1 KEY2 VALUE2 ...)

Here are the possible keys:

:rules

It should contain the rules for the task. A rule can be one of the following:

• A symbol, in which case it is retuned as is;
• A string, in which case it is a regexp that the buffer-name must match if it belongs to the task;
• A special construct: (mode mode-name), in which case the buffer belong to the task if its mode is mode-name
• A special construct: (dir "directory"), in which case the buffer belong to the task if he belongs to the tree whose root is "directory". It is useful when you want a task to be one of your project.
• A list, in which case the buffer belongs to one of the task if any of its atoms are matched.
• A function, which must returns a rule that must be matched if the buffer belong to the task.

The order of tasks are important, because rules are matched from the beginning to the end of the list. So put the most general rules in the end, and the most specific ones in the beginning.

:flying

You should put this to non-nil if you want the group to be "flying" (see section 4.2 Flying tasks and buffers), that is to say switching to a buffer belonging to such a task does not switch to the task.

:add

If it is non nil, then when this rule is matched the task is added to current task.

:persistent

When you switch buffer with the function task-switch-buffer-within-task-iswitchb, the buffers in tasks marked as persistent are always choices.

:kill-function

When you kill a task, this function will be called. Then function task-default-kill-function is called, which kills all buffers in the task. For instance, you might want to kill gnus properly, or to make all buffers flying before the task is killed. This function takes in argument the task beeing killed.

General advices:

• Remember order is important: rules are matched from the top to the bottom of this list. Newly created buffers are added on top of the list. In future release you will be able to edit the order in live, but for now, it's impossible.

The default is the following:

(setq task-properties
  '((task-Flying . (:rules nil))
    (task-Misc . (:rules "^ ?\\*.*\\*$"
			 :flying t))))

Let's look at some typical set of rules:

(setq task-properties
  '((task-elisp . (:rules ((dir "/home/racin/elisp/") (mode emacs-lisp-mode))))
    (task-c   . (:rules ((mode c-mode) (mode makefile-mode))))
    (task-webdevel . (:rules  "^\\(.*\\.xml\\|.*\\.html\\|.*\\.xsl\\|.*\\.css\\)"))
    (task-Gnus . (:rules
		  (concat "^" (regexp-opt
			       '("*Group*" "*Article*"
				 "*Summary" "*BBDB*" "*mail*" "*reply" "*Resend")))
		  :kill-function (lambda (task) (gnus-group-exit))))
    (task-Flying . (:rules nil))
    (task-Misc . (:rules "^ ?\\*.*\\*$"
			 :flying t))))

(Of course, you should have a much precise and larger set of rules).

5.2 Hooks

• task-create-hook Hook called just after a task is manually created with task-create. If you need a hook for all newly created task, use task-new-hook instead. (Note: this hook is processed after task-new-hook.)

  One of the main use of this hook is to add some buffers to the newly created task. This task is accessible via task-current. You can also use it to put your created task as flying, etc...

• task-new-hook. This hook is called when a task which did not existed is created. This can occur when you create a buffer matching a certain rule (see section 4.1.6 Rules), or when you create a task with task-create. You can access the current task with task-current. task-create

Many hooks can be easily created, so if you need it, just tell me and I'll do.

5.3 Configuration examples

Here's some way to use task-mode:

• If you mainly use tasks with rules, you should put the following in your .emacs:

  (add-hook 'task-create-hook 'task-edit-rules)

• If you don't like the "switch buffer change task" and want to switch of tasks manually, you could use the following:

  (add-hook 'task-new-hook (lambda (put task-current :flying t)))

  Note that you can still use some task-rules to put your buffers in the good places initially.

If you have tweaked a little task-mode, please send me your configuration file and I'll put it here!

6. Copying

@insertcopying

7. Thanks

• Many thanks to Christophe Garion for his function task-switch-buffer-within-task-ido
• Thanks to everybody who wrote Emacs or extensions to Emacs. I'm proud to be one of them now!

Table of Contents

1. Installation notes
2. Overview

2.1 Features
2.2 Coming soon
2.3 Known problems

3. Getting Started

3.1 Task switching
3.2 Moving buffers beetween tasks
3.3 The task rules
3.4 Using task-mode

4. Concepts

4.1 Tasks and buffers

4.1.1 Creating tasks
4.1.2 Adding buffers to tasks
4.1.3 Switching beetween tasks
4.1.4 Killing tasks
4.1.5 Changing buffers from tasks
4.1.6 Rules

4.2 Flying tasks and buffers
4.3 The Window configuration ring

5. Customization

5.1 Customizing tasks
5.2 Hooks
5.3 Configuration examples

6. Copying
7. Thanks

Short Table of Contents

1. Installation notes
2. Overview
3. Getting Started
4. Concepts
5. Customization
6. Copying
7. Thanks

About this document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four