PlannerMode

@insertcopying

1. Preface

This document describes PlannerMode, which was written by John Wiegley and is now maintained by Sacha Chua. This document is available in both the stable and development versions, and should describe the features available in the particular version it is included in.

This document is a work in progress, and your contribution will be greatly appreciated. Please e-mail comments and suggestions to the maintainer, Sacha Chua sacha@free.net.ph . In the subject line of your e-mail, include the word `PlannerMode'.

Documentation author: John Sullivan johnsu01@yahoo.com

Maintainer: Sacha Chua sacha@free.net.ph

John Sullivan (johnsu01)
April 25, 2004

2. Introduction

PlannerMode is an organizer and day planner for Emacs. It helps you keep track of your

• completed and pending tasks
• daily schedule, and
• notes

in plain text files.

PlannerMode is based on EmacsWikiMode. EmacsWikiMode enables you to create and use hyperlinks and simple formatting in plain text files. These abilities are used in PlannerMode to format your planner pages the way you like, to create links from your tasks and notes to the materials and projects they refer to, and to optionally publish your pages as HTML.

Because they are plain text with very few requirements, the organizer pages kept by PlannerMode can be as basic or as detailed as you like. Your pages can be simple to-do lists with no more additional information than what you would scrawl on a napkin, or they can be a highly technical affair involving hyperlinks, embedded Lisp code, appointment schedules and RSS feeds. As with so much in Emacs, it's all up to you.

PlannerMode and related packages are available in both stable and development versions (see section 3. Installation).

• 2004

  Damien Elmes handed EmacsWikiMode to Mark Triggs for a short period of time. Mark Triggs deferred to Sacha Chua as official maintainer of PlannerMode. Sacha Chua volunteered to maintain RememberMode.

• 2003

  Sacha Chua volunteered to maintain PlannerMode. Damien Elmes volunteered to maintain EmacsWikiMode.

• 2001

  John Wiegley wrote EmacsWikiMode and PlannerMode.

3. Installation

3.1 Installing the stable version

Choose the stable branch if you want to minimize risk. Features are added to the stable branch after meeting these conditions:

• Confirmed working by at least one other user
• Documented in the source code, changelog, and info manual

Errors are corrected in the development branch first. Once fixes are confirmed, they are applied to the stable branch. User-visible changes will be clearly marked with "NOTE:" in the changelog for the branch. Major changes will also be announced on the emacs-wiki-discuss@nongnu.org mailing list. see section 11. Getting Help and Reporting Bugs.

You will need at least `planner/planner.el' and `emacs-wiki/emacs-wiki.el' to use PlannerMode.

Debian users can get PlannerMode via apt-get. The stable version in the Debian archive is a few versions behind `sacha-stable.tar.gz'. `planner-el' is available in the Sarge and Sid distributions: apt-get install planner-el .

You can also install the source distribution.

1. Download and unpack http://sacha.free.net.ph/notebook/emacs/sacha-stable.tar.gz .
2. Edit your `~/.emacs' (`_emacs' on Microsoft Windows).

   ;; Add the directories to your load path (add-to-list 'load-path "/path/to/emacs-wiki") (add-to-list 'load-path "/path/to/planner") ;; Load planner (require 'planner)

You can browse the files or download the archive at the following locations:

• Individual files: http://sacha.free.net.ph/notebook/emacs/stable
• Archive: http://sacha.free.net.ph/notebook/emacs/sacha-stable.tar.gz
• Debian installation: apt-get install planner-el (a few versions behind `sacha-stable.tar.gz')
  • Official Debian repository (stable, testing, and unstable)
  • Unofficial Debian repository http://sacha.free.net.ph/notebook/emacs/planner/ . (sources and binaries)

• Browse arch repository: http://plannerarch.mbobo.org (Updated at 16:00 GMT, Host: Florian Lanthaler)

• Browse documentation: http://sacha.free.net.ph/notebook/doc/stable/planner/ (PDF, HTML)
• EmacsWiki entry: http://www.emacswiki.org/cgi-bin/wiki/PlannerMode

3.2 Installing the development version

Choose the development branch if you want to use new Planner features.

The Arch revision control system allows you to retrieve previous versions and select specific features and bugfixes.

Downloading the modules for the first time:

1. Install arch. Debian: apt-get install tla Other distros: see http://regexps.srparish.net/www/ .
2. Register the archive and download the modules.

   # Register the archive tla register-archive sacha@free.net.ph--main http://sacha.free.net.ph/notebook/arch # Download emacs-wiki module into the emacs-wiki/ subdirectory tla get sacha@free.net.ph--main/emacs-wiki--dev--1.0 emacs-wiki # Download planner module into the planner/ subdirectory tla get sacha@free.net.ph--main/planner--dev--1.0 planner

3. Open your `~/.emacs' (`_emacs' on Microsoft Windows) and add the `emacs-wiki/' and `planner/' directories to your load path.

   (add-to-list 'load-path "/path/to/emacs-wiki") (add-to-list 'load-path "/path/to/planner")

To list upstream changes not in local copy:

# Change to the source directory you are interested in. Example:
cd emacs-wiki/

# Display the summary of changes
tla missing --summary

To update to the latest version:

cd emacs-wiki
tla replay
cd ../planner
tla replay

You can browse the files or download the archive at the following locations:

• Individual files: http://sacha.free.net.ph/notebook/emacs/dev
• Archive: http://sacha.free.net.ph/notebook/emacs/sacha-dev.tar.gz
• Browse arch repository: http://plannerarch.mbobo.org (Updated at 16:00 GMT, Host: Florian Lanthaler)
• Browse documentation: http://sacha.free.net.ph/notebook/doc/dev/planner/ (PDF, HTML)
• EmacsWiki entry: http://www.emacswiki.org/cgi-bin/wiki/PlannerMode

3.3 Components

The PlannerMode archive contains a number of files. A minimal installation includes `planner/planner.el' and `emacs-wiki/emacs-wiki.el'.

PlannerMode is closely integrated with RememberMode and Emacs-Wiki Mode. Currently, integration with Muse is also being developed. Many of the optional files relate to the integration with these different modes, and are very helpful for getting all of them to work together.

RememberMode does not depend on PlannerMode or Emacs-Wiki, but works best with PlannerMode installed.

EmacsWikiMode can be used without any of the other modules.

You can find descriptions of each file in the source code and in this info page.

3.4 Advanced Installation

Once you decide you want to keep PlannerMode around for a while, there are two additional steps you can take to make using it easier and more efficient. These steps are optional.

1. You can make this document, the PlannerMode info file, appear in the index of info files you see when you type M-x info or C-h i in Emacs. The instructions for doing this vary depending on whether you have permission to edit certain files on your system. Follow the instructions in section `Installing an Info File' in Texinfo, using something like:

   * PlannerMode: (path/to/planner/PlannerMode). Organizer/day planner for Emacs.

   for the new entry in the info `dir' file.

2. You can byte-compile `planner.el', `emacs-wiki.el', `remember.el', or any of the optional modules you frequently use, in order to improve the speed of their execution. Basically, all you need to do is visit each file in an Emacs buffer and do M-x byte-compile-file. To read more detail about byte compilation, see section `Byte Compilation' in Emacs Lisp Reference Manual.

4. Overview

You can use PlannerMode to keep track of your tasks, schedule, notes, and other information you want to store in hyperlinkable text files. PlannerMode is flexible and can support many different ways of working.

You can get the most benefit out of a personal information manager if you use it everyday. Most people add (plan) to the end of their `~/.emacs' so that PlannerMode shows today's schedule and unfinished tasks.

The most important feature of Planner is its ability to pick up information from the buffer you are currently looking at. You can use (require 'planner-auto) in your `~/.emacs' to have it automatically load the corresponding Planner module when you use other extensions of Emacs. Use M-x planner-create-task-from-buffer to create a task linked to the current buffer. If you want to have the same annotations available for notes, please check out RememberMode. (see section 3. Installation.)

Another important feature is Planner's ability to let you jot down tasks and notes without being distracted from your work. If you bind planner-create-task-from-buffer to a shortcut key, you can easily create tasks from anywhere. If you want to be able to take annotated notes with the same ease, please check out RememberMode. (see section 3. Installation.) The following code sets F9 to it.

(global-set-key '[f6] 'planner-create-task-from-buffer)

planner-goto-today, planner-goto, and planner-annotation-as-kill are also handy functions.

Last but not least, the customizability of Planner means you can make your personal information manager truly personal. People have different ways of organizing their day, and Planner strives to be as flexible as possible. Please check out our mailing list at http://lists.nongnu.org/mailman/listinfo/emacs-wiki-discuss . We love adapting Planner to people's needs.

For example, you can tweak the way Planner organizes files.

• Tasks, schedule and notes on day pages.

  By default, tasks, schedule entries and notes are filed on day pages. This makes it easy for you to see all the entries relevant to a single day without becoming overwhelmed with information. Unfinished tasks are carried over to the next day when you use M-x plan, so it's always kept up to date. Completed tasks are left on the day page you finished them on, which helps when reviewing one's progress and writing accomplishment reports.

• Cross-referenced with plan pages.

  You can associate your tasks with projects either when you create the task or later, with M-x planner-replan-task. This makes it easy for you to see all the information associated with a particular project. If you use RememberMode to create notes, you will also be able to associate notes with a plan page.

• Just plan pages.

  If your tasks don't usually have dates, you can turn day pages off by customizing planner-use-day-pages. If so, then all of your tasks and notes will be stored on the WelcomePage and/or a plan page.

Other customizations are possible. You don't have to be a programmer. You just have to have an idea of how you'd like things to work. Hope you have fun using Planner!

5. Example Configurations

There is no One True Way to plan. Every person is different. We hope you'll find a good starting point among the example configurations below. If what you want to do does not perfectly fit under one of these examples, please post a description of the way you plan. We look forward to helping you customizing planner to fit your needs.

5.1 Bare-Bones Planning

You can keep all of your tasks, notes and schedules in a single file: WelcomePage. This is good for people who are used to storing all of their information in a flat text file. By storing your information in planner, you'll be able to take advantage of automatic hyperlinking to files and other resources. You can also sort your tasks by priority and status.

To set your system up for bare-bones planning, set the planner-use-day-pages variable to nil before loading planner. For example, you can put this in your `~/.emacs' (or `_emacs'):

(setq planner-use-day-pages nil)
(setq planner-default-page nil)
(require 'planner)

When you create a task or note, planner will not prompt you for a date. If you press RET when prompted for a plan page, it will accept the default of nil, so no other plan pages will be used. All of your data will be kept in one file, which can then be easily backed up.

You can use commands like planner-create-task-from-buffer to create tasks, or you can type tasks in manually. You can edit or delete anything in the page without having to update other files.

5.2 Bare-Bones Planning with Plan Pages

When you create a task or note, Planner.el can copy this to a plan page. Plan pages allow you to see an overview of all the data for a project.

For convenience, the planner-create-task-from-buffer command prompts you for a plan page when you create a task.

5.3 Tasks on Plan Pages with Some Day Pages

If most of your tasks are associated with plan pages but you want to schedule some tasks on day pages, you can leave day pages on (default) and then write a function that turns off day pages. For example, the following code snippet turns off day pages for task creation from buffers.

(require 'planner)

(defun my-planner-create-task-from-buffer ()
  "Call `planner-create-task-from-buffer', but without dates."
  (interactive)
  (let ((planner-use-day-pages nil))
    (call-interactively 'planner-create-task-from-buffer)))

5.4 Hierarchical Tasks

You can use `allout.el' or other modes for outlining to support hierarchical tasks in plan pages. No special support is needed.

Tasks created by planner-create-task-from-buffer and planner-create-task are created in the `* Tasks' section. If planner-add-task-at-end-flag is non-nil, tasks are added to the end of the first task block, else they are added to the beginning. You can then copy and paste tasks into your preferred hierarchy. Blank lines delimit blocks of tasks upon which automatic sorting is performed.

You can also type in tasks manually. You may find this approach faster when you are comfortable with planner.

For example, a `LearnPlanner' plan page might contain the following lines:

* Learn how to use planner.el

** Installation

#C0 _ Decide whether you want stable or devel
#C0 _ Download the archives

** Configuration

*** Load path

#C0 _ Figure out how to add things to my load path
#C0 _ Actually add it to my load path

...

If you create tasks for the finest level of detail available at the moment, you can schedule them onto day pages with C-c C-c (planner-copy-or-move-task). Then you can use planner-jump-to-link to switch between the day page and the plan page link.

6. Getting Started

6.1 Basic Configuration

You may want to customize the following variables before you begin using PlannerMode.

User Option: planner-directory

Plain-text planner files will be stored in this directory. Default: `~/Plans'.

User Option: planner-publishing-directory

Planner HTML files will be published to this directory. If you want to view your tasks, schedule and notes using a web browser, upload the contents of this directory to your website. Default: `~/WebWiki'.

If you change these variables after Planner is loaded, please be sure to run M-x planner-update-wiki-project. It might be a good idea to add (planner-update-wiki-project) to the end of your `~/.emacs'.

6.2 Starting with Day Pages

planner-goto-today opens today's page. Day pages are named `YYYY.MM.DD' and contain your notes for the day.

You should see a file that looks like this:

* Tasks


* Schedule

* Notes

You can type anything you want into this file. You can add or delete sections. When you save, Emacs stores your information in planner-directory.

Use the following commands to navigate through day pages:

Function: plan

Start planning the day. If planner-carry-tasks-forward is non-nil, copy the most recent unfinished tasks to today's page, else open the most recent page.

Function: planner-goto (C-c C-j C-d)

Prompt for a date using a calendar pop-up and display the corresponding day page. You can specify dates partially. The current year and month are used if omitted from the input. For example, if today is 2004.05.05, then

• +1 is one day from now, or `2004.05.06'
• -1 is one day before now, or `2004.05.04'
• 12 is equivalent to `2004.05.12'
• 8.12 is equivalent to `2004.08.12'
• 2005.08.12 is a full date specification

In the calendar buffer, you can also left-click or press RET on a date to select it.

Function: planner-goto-today (C-c C-j C-j)

Display today's page. Create the page if it does not yet exist.

Function: planner-goto-tomorrow (C-c C-j C-t)

Goto the planner page days after the currently displayed date. If days is nil, go to the day immediately after the currently displayed date. If the current buffer is not a daily planner page, calculate date based on today.

Function: planner-goto-yesterday (C-c C-j C-y)

Goto the planner page days before the currently displayed date. If days is nil, go to the day immediately before the currently displayed date. If the current buffer is not a daily planner page, calculate date based on today.

Function: planner-goto-most-recent

Go to the most recent day with planning info.

Function: planner-goto-previous-daily-page

Goto the last plan page before the current date. The current date is taken from the day page in the current buffer, or today if the current buffer is not a planner page. Do not create pages if they do not yet exist.

Function: planner-goto-next-daily-page

Goto the first plan page after the current date. The current date is taken from the day page in the current buffer, or today if the current buffer is not a planner page. Do not create pages if they do not yet exist.

Function: planner-goto-plan-page page

Opens page in the the planner-project Wiki. Use planner-goto if you want fancy calendar completion.

Function: planner-show date

Show the plan page for date in another window, but don't select it. If no page for date exists, return nil.

6.3 Tasks

6.3.1 Creating a Task

You can create a task from any buffer in Emacs by invoking M-x planner-create-task-from-buffer.

This command does more than just add an item to your list of tasks. It also connects that item to some useful context information.

If you create a task while viewing any buffer other than a PlannerMode day page, PlannerMode will associate the task with a hyperlink to that buffer. Try it now by creating a task from this Info buffer.

1. M-x planner-create-task-from-buffer
2. When prompted for the task name, enter Learn how to change a task's status and press RET.
3. When prompted for the date, press RET to schedule the task for today.
4. When prompted for the project page, press RET to accept the default page of `TaskPool'. This is a page for tasks not connected to a larger plan.

PlannerMode prompts you for two pieces of information when you ask it to create a task. First, it asks you when you would like to have the task show up in your planner. If you would like it to be scheduled for today, you can just hit RET. If you would like it to be scheduled for some day during the current month, you can just enter the date, without the month, like `16'. If you would like it to be scheduled for some day in a future month of the current year, you can enter just the month and date, like `06.16'. If you would like to schedule something for next year, then enter the full date, like `06.16.2005'. If you do not want this task to appear on a day page at all, you can enter `nil'.

The second piece of information PlannerMode asks for is the name of the project to associate the task with. In the above example, you associated the task with the project "TaskPool", which means that you did not want to associate the task with a particular project or goal in your life. Another way to do this is to answer the project prompt by entering `nil'. But instead, you might enter `LearnPlanner' as the project. This creates a new page called "LearnPlanner" in your planner directory and places an entry for the task on that page.

The task then exists in two places: once on your day page, to show how it fits into your daily work; and once on a project page, to show how it fits into your larger projects and goals. In the future you might add related tasks like, "Memorize PlannerMode keybindings". These tasks might be scattered over weeks or months worth of day pages, but as long as you enter the same project name for each, you will have a way to look at them all together on a single project page.

PlannerMode also creates hyperlinks to enable you to easily move back and forth between the day page system and the project page system. Each task on a day page will have a hyperlink to its project page. Each task on a project page will have a hyperlink to its day page.

After using PlannerMode for a while, you may find yourself with quite a few project pages. Keep in mind that completion is enabled at the project prompt when you create a task, so hitting SPC or TAB at the prompt will show you a list of your current project pages.

Once the task is created, you are returned to the buffer you were working in again, PlannerMode gets out of your way, and you can go on about your business. Later on, when you decide to actually work on that "Memorize PlannerMode keybindings" task, you will be able to follow the hyperlink from that task on your day or project page directly to the relevant node in the PlannerMode info file!

By default, M-x planner-create-task-from-buffer creates high-priority tasks, marked with the letter `A'. But you can specify a particular priority by calling:

• M-x planner-create-high-priority-task-from-buffer for `A'
• M-x planner-create-medium-priority-task-from-buffer for `B'
• planner-create-low-priority-task-from-buffer for `C'

You can change the default priority of planner-create-task-from-buffer by customizing planner-default-task-priority.

You don't have to use planner-create-task-from-buffer to create tasks. You can also create new tasks manually by typing them directly on your day or project page in the format PlannerMode expects. You can even still create hyperlinks by using EmacsWiki formatting as you manually type the new task. Keep in mind also that tasks do not have to be linked to any other page.

For convenience, planner-create-task-from-buffer is bound to C-c C-t in PlannerMode buffers. You can bind planner-create-task-buffer to a shortcut key. See the manual for your Emacs distribution to find out more about keybinding.

Function: planner-create-task-from-buffer title date plan-page

Create a new task named title on date based on the current buffer.

With a prefix, associate the task with the current planner page. If you create a task on a date page, you will be prompted for a plan page. If you create a task on a plan page, you will be prompted for a day page. If nil is specified, the task is created only on the current page.

See planner-create-task for more information.

The new task is created at the top or bottom of the first block of tasks on the scheduled day page (if any), depending on the value of planner-add-task-at-end-flag.

Function: planner-create-task title date annotation plan-page

Create a new task named title based on the current Wiki page. If date is non-nil, makes a daily entry on date, else makes an entry in today's planner page. It's assumed that the current Wiki page is the page you're using to plan an activity. Any time accrued to this task will be applied to that page's name in the timelog file, assuming you use timeclock (see section `Time Intervals' in GNU Emacs Manual). If annotation is non-nil, it will be used for the page annotation. If plan-page is non-nil, the task is associated with the given page.

With a prefix, associate the task with the current planner page. If you create a task on a date page, you will be prompted for a plan page. If you create a task on a plan page, you will be prompted for a day page. If nil is specified, the task is created only on the current page.

You probably want to call planner-create-task-from-buffer instead.

The new task is created at the top or bottom of the first block of tasks on the scheduled day page (if any), depending on the value of planner-add-task-at-end-flag.

6.3.2 Viewing tasks

Review the tasks scheduled for today by typing M-x planner-goto-today. If you created the task from the previous section in this tutorial, you should see a line that looks like

#A0  _ Learn how to change a task's status from Tasks (TaskPool)

From left to right, these are what the symbols mean:

• `A' - Priority. A (high)
• `0' - Priority number. It is calculated whenever you save the file or call planner-renumber-tasks. Tasks are numbered in ascending order according to priorities.
• `_' - Status. _ (unfinished)

If you click on `Tasks' or press RET while your cursor is in the link, Emacs will display the previous info page.

If you select `TaskPool', Emacs will display the `TaskPool' plan page. Plan pages organize your tasks and notes about a project in one file.

You can use planner-seek-next-unfinished-task to move to the next unfinished task on the current page.

Function: planner-list-tasks-with-status status

Display all tasks that match the status regular expression.

Function: planner-list-unfinished-tasks

Display all unfinished tasks.

Function: planner-jump-to-linked-task task-info

Display the task page linked to by the current task or task-info.

6.3.3 Task Priorities

You can set the priority of a task when you create it, rather than waiting to adjust it after the fact. In order to do this, call the function corresponding to the priority you want. You probably want to bind these functions to some keys if you intend to use them much.

• planner-create-high-priority-task-from-buffer creates a task with priority `A'.

• planner-create-medium-priority-task-from-buffer creates a task with priority `B'.

• planner-create-low-priority-task-from-buffer creates a task with priority `C'.

Task priorities are confusingly called categories in the code, and what the code calls priorities are actually task numbers. This is because there are two ways of describing the priority of a task: a general priority (high, medium, low) and a specific priority (do this first, then that). You can actually use just one general category, but using more than one color-codes your tasks and gives you a better overview of your day.

6.3.4 Changing Tasks

To select a task, move your cursor to the line containing the task.

Change a task's priority (`A', `B' or `C') by editing the line. `#A' tasks are important. `#B' are medium priority. `#C' are low priority. Whenever you save the file or call M-x planner-fix-tasks, tasks are sorted and numbered according to priority and status.

Change a task's status by calling one of the following functions:

• planner-task-in-progress `o' (C-c C-z)
• planner-task-done `X' (C-c C-x)
• planner-task-cancelled `C' (C-c C-S-x)
• planner-task-delegated `>'
• planner-task-pending `P'
• planner-task-open `_'

After changing the status using a function, look at the `TaskPool' plan page. The task is also updated on the linked page. If you changed the task status manually by replacing the status with another character, you will need to call planner-update-task to update the linked page.

To reschedule a task, call planner-copy-or-move-task (C-c C-c) and choose a new date. You can mark a region and type M-x planner-copy-or-move-region to reschedule all the contained tasks to a different date. To change the plan page associated with a task, call planner-replan-task. `nil' for either input means none.

If you need to change the description of a task, do not edit the plain text file without updating the linked plan page as well. You can use planner-edit-task-description to do this. You can also use planner-delete-task to remove the task from both pages and then create it again.

To remind yourself to do tasks in a certain order, simply edit the lines so that they're in the order you want. planner-raise-task and planner-lower-task update the priorities on linked pages automatically. You can organize tasks into groups by putting a blank line between groups of tasks. PlannerMode will maintain the groupings and only sort the tasks within that group.

Function: planner-replan-task page-name

Change or assign the plan page for the current task. page-name is the new plan page for the task. Use planner-copy-or-move-task if you want to change the date.

Function: planner-raise-task-category

Change a low-priority task to a medium-priority task and a medium-priority task to a high-priority task (C to B to A).

Function: planner-lower-task-category

Change a high-priority task to a medium-priority task and a medium-priority task to a low-priority task (A to B to C).

Function: planner-raise-task arg

Raise the priority of the current task by arg steps. By default, arg is 1.

Function: planner-lower-task arg

Lower the priority of the current task by arg steps. By default, arg is 1.

Function: planner-edit-task-description description

Change the description of the current task, updating the linked page if any.

Function: planner-delete-task

Delete this task from the current page and the linked page.

Function: planner-update-task

Update the current task's priority and status on the linked page. Tasks are considered the same if they have the same description. This function allows you to force a task to be recreated if it disappeared from the associated page.

Note that the text of the task must not change. If you want to be able to update the task description, see `planner-id.el' or planner-edit-task-description.

6.3.5 Carrying Over Unfinished Tasks

The plan command reminds you of unfinished tasks. If planner-carry-tasks-forward is non-nil, then past unfinished tasks are rescheduled for today. If planner-carry-tasks-forward is nil, the most recent page is displayed.

If you want PlannerMode to scan the last three days for unfinished tasks and carry them forward, add the following lines to your `~/.emacs' (or `_emacs'):

;; Move unfinished tasks to today's page
(setq planner-carry-tasks-forward t)
;; Scan three pages in the past
(plan 3)

See planner-install-extra-task-keybindings for additional shortcuts.

Function: planner-copy-or-move-task date force

Move the current task to date. If this is the original task, it copies it instead of moving. Most of the time, the original should be kept in a planning file, but this is not required. If force is non-nil, the task is moved regardless of status. It also works for creating tasks from a Note. Use planner-replan-task if you want to change the plan page in order to get better completion. This function is the most complex aspect of `planner.el'.

Function: planner-copy-or-move-region beg end date muffle-errors

Move all tasks from beg to end to date. If this is the original task, it copies it instead of moving. Most of the time, the original should be kept in a planning file, but this is not required. planner-copy-or-move-region will copy or move all tasks from the line containing beg to the line just before end. If muffle-errors is non-nil, no errors will be reported.

6.3.6 Task Detail

You may find your planner pages getting very full, so that you want to have one broad task entry be linked to a more specific list of sub-tasks. Or, maybe you want to have a number of notes linked to a particular task.

This can be done with targets. You can have a task that is really a meta-task:

#A1  _ Do things in RevelleLog#13 {{Tasks:101}} (RevelleLog)

`RevelleLog#13' could then be a list of sub-tasks in the form of a note, or any kind of note.

Or, instead of pointing to a particular note on `RevelleLog', you could have the whole page be tasks that you enter in manually, without linking them to another page. You can just type them in like this:

#A1  _ First specific thing to do

This way, the tasks will only appear on this specific project page, and not on any daily page, so you only see them when you want to look up all of the specific tasks associated with `#A1 _ Do things in RevelleLog {{Tasks:101}} (RevelleLog)'.

As you can see, the ability to manually enter tasks is one of PlannerMode's nicest features. It allows you to create tasks that are not assigned to a specific date (by manually entering them on a project page with no date) or to a specific project (by manually entering them on a day page with no project). Yet as long as you enter them using the syntax it understands, PlannerMode will continue to recognize them as tasks.

Another way to have a task not be connected to a particular date is to do C-c C-c (planner-copy-or-move-task) and specify `nil' when asked for the date.

If you would like to see a list of all of your unfinished tasks, do M-x planner-list-unfinished-tasks. This function only checks day plan pages, not project pages.

6.3.7 Task Numbering

By default, tasks are numbered according to their position on the page. Task numbers allow you to refer to tasks using emacs-wiki links. For example, the `#A1' task in `2004.08.16' can be referred to as `2004.08.16#A1'.

Note that task numbers change every time you re-sort and re-number tasks with planner-fix-tasks. As a result, they are only reliable for references to past tasks.

If you find yourself not using this functionality, you can turn off task numbers by using the following option.

User Option: planner-use-task-numbers

Non-nil means use task numbers when creating tasks. This allows you to refer to past tasks if your tasks are numbered appropriately. If you set this to nil, you can save space in your plan files.

6.4 Schedule

This is pretty free-form. I usually have entries of the form:

hh:mm | hh:mm | activity
hh:mm | hh:mm | activity
hh:mm | hh:mm | activity

6.5 Notes

.#1 Headline
Body

and are outlined at the H3 level. If you want to take notes conveniently, check out `remember-planner.el'.

PlannerMode by default organizes the notes on a planner page so that the most recent note is first. Each note is numbered, with the oldest note labeled `.#1'. If you would like to reverse this behavior, look at C-h v planner-reverse-chronological-notes.

Notes are associated with day pages, but can also be associated with plan pages when they are created. A linked note looks like this:

.#1 Headline (LinkedNote#1)
Text

You can jump to the linked note with planner-jump-to-linked-note.

Deleting a note can be dangerous, as the notes are automatically numbered. Removing a note could break links in other pages.

Function: planner-create-note page

Create a note to be remembered in page (today if page is nil). If planner-reverse-chronological-notes is non-nil, create the note at the beginning of the notes section; otherwise, add it to the end. Position point after the anchor.

Function: planner-create-note-from-task

Create a note based on the current task and update the current task to link to the note.

Function: planner-renumber-notes

Update note numbering.

Function: planner-jump-to-linked-note note-info

Display the note linked to by the current note or note-info if non-nil.

Function: planner-search-notes regexp limit

Return a buffer with all the notes returned by the query for regexp. If called with a prefix argument, prompt for limit and search days on or after limit.

6.6 Example Page

The format of a planning file is given below. You are responsible for keeping it looking like this. I intentionally did not make PlannerMode heavy on the UI side of things, to keep it more free-form and open. This lets you adapt it to whatever your particular preferences might be.

----------------------------------------------------------------------
* Tasks

#A1 _ An open task, very important!
#A2 X A closed task (MyPlan)
#A3 o A task that's delayed, or delegated (MyPlan)

* Notes

.#1 This is note number one

Notes on note number one!

.#2 This weird ".#2" syntax is used because it's what allout.el likes for enumerated lists

It makes using allout-mode very handy.

6.7 Planner Tags

These tags are interpreted when the planner pages are published.

6.7.1 <notes>

`<notes>' is replaced by a list of note headlines on the current page. For example, the notes tag in the following example will be replaced by the two headlines when published.

<notes>

* Notes

.#1 This is a headline

and this is body text

.#2 This is another headline

and this is more body text

`<notes>' is useful if you want to provide a quick summary of blog entries at the top of your page. Just add it to your planner-day-page-template.

6.7.2 <past-notes>

`<past-notes>' is replaced by an index of note headlines. If start is specified, it lists notes starting from that date. If directory is specified, you can index notes in another planner directory.

All the notes I've taken as a 21-year-old:

<past-notes start="2004.08.12">

6.7.3 <tasks>

`<tasks>' is replaced by a report of tasks over all day pages.

All incomplete tasks

<tasks status="^X">

All completed tasks

<tasks status="X">

All tasks

<tasks>

Warning: this function can be slow, as it checks all the day pages!

7. Planner Features

Now that you have been introduced to the basics, here is some specific information about working with the different aspects of PlannerMode.

7.1 Making Files Pretty

By default, planner does a little bit of fancy reformatting when you save a file. The following options control this behavior:

User Option: planner-sort-tasks-automatically

Non-nil means sort tasks whenever a planner file is saved. On day pages, tasks are sorted by status. On plan pages, they are sorted by status and date. Sorting can take a while.

User Option: planner-renumber-tasks-automatically

Non-nil means renumber tasks from 1 to N whenever a planner file is saved. This allows you to refer to tasks in previous day pages using anchors like `2003.08.12#A1'.

User Option: planner-align-tasks-automatically

Non-nil means align tasks whenever a planner file is saved. This causes the status to line up in a neat column if you have less than 100 tasks.

User Option: planner-renumber-notes-automatically

Non-nil means renumber the notes. If most of your notes are only on one page, you might like seeing the notes numbered in order. If you use a lot of cross-referencing, note renumbering will break those links.

Function: planner-sort-tasks

On day pages, sort tasks according to category and position. On plan pages, sort according to status, category, date, and position.

Function: planner-renumber-tasks

Update task numbering.

Function: planner-align-tasks

Align tasks neatly. You can add this to write-file-functions to have the tasks automatically lined up whenever you save. For best results, ensure planner-align-tasks is run after planner-renumber-tasks.

Function: planner-fix-tasks

Sort, renumber and align tasks.

Tasks are sorted by category (ABC) and status (_oP>XC) on day pages.

On plan pages, tasks are sorted by category (ABC), status (XC), and date. By default, undated tasks are sorted after dated tasks. If you want undated tasks listed first, customize planner-sort-undated-tasks-equivalent.

User Option: planner-sort-undated-tasks-equivalent

This option controls the behavior of task sorting on plan pages. By default, the value `9999.99.99' causes dated tasks to be listed before undated tasks. To sort undated tasks before dated tasks, set this to a blank string.

7.2 Annotations

The context included when you create a task and the context included when you create a note are gained the same way. It sounds like black magic, but it turns out not to be.

All that happens is, PlannerMode has a list of functions, planner-annotation-functions. When you create a task from a buffer, or remember a note from a buffer, PlannerMode goes through this list from top to bottom. The first one that returns true is the one it uses.

For example, if you're in Wanderlust, and you hit the key you've bound to planner-create-task-from-buffer, it looks at this list and does something like this. Is it an ERC buffer? No. Is it a BBDB buffer? No. Are we in w3m? No. Are we in Wanderlust? Yes. So this function succeeds. It stops searching and runs the annotation function for Wanderlust, which in this case finds out who the message is from and what the message ID of the message is. It then takes those and constructs a link back to that message, with a link title something like `Email from Joe Blogs'.

So, you've read the email from Joe Blogs. He's asked you to do something and you've hit your key to add that task to your list of things to do. So what you end up with is a description of the task, and a link back to what made you create the task in the first place.

The same happens with remembering notes, except that it ends up in the `* Notes' section of your page instead.

By default, `planner.el' can annotate tasks and notes based on the current filename. To change the behavior of annotations, customize the following options:

User Option: planner-annotation-functions

A list of functions tried in order by planner-create-task-from-buffer and other functions that pick up context. The first non-nil value returned is used as the annotation. To cause an item to not be annotated, return the empty string `""'.

User Option: planner-annotation-strip-directory

File links are usually generated with the full path to the file so that you can easily tell apart files with the same base name. If planner-annotation-strip-directory is non-nil, though, only the base name of the file will be displayed. For example, a link to `/foo/bar/baz' will be displayed as `baz' and hyperlinked to the file.

User Option: planner-annotation-use-relative-file

If t, always use relative filenames. planner-annotation-use-relative-file can also be a function that takes the filename and returns non-nil if the link should be relative. Filenames are resolved relative to planner-directory. That is, the created link will be of the form `../../somefile' instead of `/absolute/path/to/file'. This can be helpful if you publish your planner files to the Net and your directory structure ensures that relative links resolve the same from planner-directory and planner-publishing-directory.

7.3 Interactive Lisp with planner-lisp.el

You can include interactive Lisp functions in your planner pages.

First, you need `planner-lisp.el'. Put this in your `.emacs' (or `_emacs'):

(require 'planner-lisp)

Then, add a link to the Lisp function to your page, like:

[[lisp://plan][Plan]]

This will be rendered as `Plan'. Selecting the link will run the plan function interactively.

`planner-lisp.el' does not provide any interactive functions or keybindings.

7.4 Generating Daily Accomplishment Reports

You can use `planner-accomplishments.el' to get a summary of your task activity for a particular day. The report is grouped by status and plan (on day pages) or date (on plan pages). An example report follows:

Link        | Unfinished | In progress | Delegated | Completed | Total
nil         | 1          | 0           | 0         | 6         | 7
TaskPool    | 1          | 1           | 0         | 3         | 5
PlannerMode | 0          | 0           | 1         | 1         | 2
SchoolWork  | 0          | 0           | 0         | 1         | 1
Total       | 2          | 1           | 1         | 11        | 15

This lets you see how you balance your time between your projects.

There are currently two ways to use `planner-accomplishments.el'.
• Displaying a temporary buffer

  You can call planner-accomplishments-show to display a buffer containing the current page's accomplishment report.

• Rewriting sections of your planner

  Choose this approach if you want accomplishment reports to be in their own section and you would like them to be readable in your plain text files even outside Emacs. Caveat: The accomplishment section should already exist in your template and will be rewritten when updated.

  To use, set planner-accomplishments-section to the name of the section to rewrite (default: `Accomplishments'). If you want rewriting to be automatically performed, call planner-accomplishments-insinuate. The accomplishments will be rewritten whenever you save a planner page. If you want rewriting to be manual, call planner-accomplishments-update.

User Option: planner-accomplishments-section

Header for the accomplishments section in a plan page. Used by planner-accomplishments-update.

User Option: planner-accomplishments-status-display

Alist of status-label maps also defining the order of display. Used by planner-accomplishments-format-table.

Function: planner-accomplishments-insinuate ()

Automatically call planner-accomplishments-update when saving tasks in planner-mode buffers.

Function: planner-accomplishments-update ()

Rewrite planner-accomplishments-section with a summary of tasks on this page.

Function: planner-accomplishments-show ()

Display a buffer with the current page's accomplishment report.

7.5 Seeing an Overview of Tasks

You can see a list of tasks with `planner-tasks-overview.el'. Seeing how you've scheduled tasks over the next few days can help you decide when to schedule another task. Table entries will be of the form

date | link | priority status | task-description

To display the tasks between a set of day pages, use

Function: planner-tasks-overview start end

Display an overview of your tasks from start to end. If start is nil, start from the very first day page. If end is nil, include the very last day page. You can use planner-expand-name shortcuts here, like +1 or -1. Pressing RET at the prompt will use today.

Once in a planner-tasks-overview buffer, you can use the keyboard shortcut o to change the overview period.

You can sort the task display with the following functions:

Function: planner-tasks-overview-sort-by-date

Sort the tasks by date. Keyboard shortcut: 1

Function: planner-tasks-overview-sort-by-plan

Sort the tasks by associated plan page. Keyboard shortcut: 2

Function: planner-tasks-overview-sort-by-category

Sort the tasks by category. Keyboard shortcut: 3

Function: planner-tasks-overview-sort-by-status

Sort the tasks by status. Keyboard shortcut: 4

You can jump to linked tasks with

Function: planner-tasks-overview-jump other-window

Display the current task. If a prefix argument is supplied, show the task in another window. Keyboard shortcut: j

Function: planner-tasks-overview-jump-other-window

Display the current task in another window. Keyboard shortcut: C-u j

TAB, SHIFT-TAB and RET navigate links in the usual fashion.

7.6 Publishing Calendars

Here is an example Emacs Lisp snippet that automatically publishes calendars in your day pages.

(require 'planner-calendar)
(add-hook
 'planner-mode-hook
 (lambda ()
   "Add the relevant hooks for `planner-calendar' to work."
   (add-hook 'emacs-wiki-before-markup-hook
             'planner-calendar-insert-calendar-maybe nil t)
   (add-hook 'emacs-wiki-after-file-publish
             'planner-calendar-create-today-link nil t)
   (add-hook 'emacs-wiki-after-markup-hook
             'planner-calendar-move-calendar-to-top-of-page-maybe nil t)))

User Option: planner-calendar-prev-month-button

HTML text used for previous month buttons.

User Option: planner-calendar-next-month-button

HTML text used for next month buttons.

User Option: planner-calendar-day-header-chars

Number of characters to use for day column header names.

User Option: planner-calendar-today-page-name

Default Emacs-Wiki base name for published today page link.

Function: planner-calendar-insert-calendar-maybe

Add this function to emacs-wiki-before-markup-hook in planner-mode buffers in order to automatically add a day page during the calendar. This cannot be done from the page header because the inserted text still needs to be processed.

Function: planner-calendar-create-today-link

Add this function to emacs-wiki-after-file-publish-hook to create a "today" soft-link to the newest published planner day page, on operating systems that support POSIX ln.

Function: planner-calendar-move-calendar-to-top-of-page-maybe

Add this function to emacs-wiki-after-markup-hook if you want the calendar inserted by planner-calendar-insert-calendar-maybe to be moved to the beginning of the page. This work-around is necessary because some functions used by `planner-calendar.el' only work during markup.

7.7 Authz Access Restriction

`planner-authz.el' was written by Andrew J. Korty in order to allow the easy restriction of portions of published pages. It uses the HTML::Mason module available on CPAN (http://www.cpan.org). Setting up HTML::Mason is outside the scope of this document. Make sure that it works before trying out `planner-authz.el'.

`planner-authz.el' modifies the behavior of emacs-wiki-publish so that published pages follow access modifiers.

This library lets you publish your planner pages while controlling access to certain portions of them to users you specify. When you load this library, you gain access to two additional markup directives to use in your planner pages. The `<authz>' tag lets you restrict access to arbitrary content as follows:

Here is a sentence everyone should see.  This sentence also
contains no sensitive data whatsoever.  <authz users="ajk">This
sentence, however, talks about my predilection for that French
vanilla instant coffee that comes in the little tin, and I'm
embarrassed for anyone else to know about that.</authz> And
here's some more perfectly innocuous content.

You can use `<authz>' tags to mark up entire paragraphs, tasks, notes, and anything else. The tags are replaced with Mason code in the published pages.

The `#authz' directive restricts access to an entire page. A Mason call is added to this page to generate a 403 error when someone not listed tries to access it. Any notes or tasks on a `#authz'-protected page are also wrapped in Mason code on linked pages. To add a `#authz' directive to an emacs-wiki page, place `#authz' followed by a space-delimited list of users on one line. For example:

#authz ajk sacha

User Option: planner-authz-project-default

Default access list for project pages (not day pages). If a given project page doesn't contain a `#authz' tag, it will receive the access list defined here. If this variable is nil, all users will be allowed to view the page. No corresponding variable is provided for day pages because it doesn't seem like you'd ever want to control access based on what day it was. (But I will accept patches. :) Notes and tasks referencing pages without `#authz' tags will also be restricted to the users listed here.

User Option: planner-authz-day-note-default

Default access list for notes on day pages not associated with any project. There is way to set a default for notes on project pages for the reason above; they would only be associated with date pages anyway.

User Option: planner-authz-day-task-default

Same as planner-authz-day-note-default, but for tasks.

Function: planner-authz-publish-index

Publish an index for the planner marked up with Mason code. Only those links to pages which the remote user is authorized to access will be shown.

7.8 Task IDs

After loading `planner.el', make sure that `planner-id.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-id)

This module modifies the behavior of `planner.el', adding global task IDs so that tasks can be edited and updated. Planner IDs are of the form `{{Identifier:Number}}'.

User Option: planner-id-add-task-id-flag

Non-nil means automatically add global task IDs to newly-created tasks. If nil, use planner-id-add-task-id to add IDs to existing tasks, or planner-id-add-task-id-to-all to add to all tasks on the current page. (Development version 2004.05.05: planner--dev--1.0--patch-81)

User Option: planner-id-update-automatically

Non-nil means automatically update linked tasks whenever a page is saved. If nil, use planner-update-task to update the linked task. By default, linked tasks are automatically updated.

User Option: planner-id-tracking-file

File that contains ID tracking data. This file is automatically overwritten.

The following interactive functions are defined in `planner-id.el':

Function: planner-id-jump-to-linked-task &optional info

Display the linked task page. If info is specified, follow that task instead.

Function: planner-id-add-task

Add a task ID for the current task if it does not have one yet. Update the linked task page, if any.

Function: planner-id-update-tasks-on-page &optional force

Update all tasks on this page. Completed or cancelled tasks are not updated. This can be added to write-file-functions. If force is non-nil, completed and cancelled tasks are also updated.

Function: planner-id-add-task-id-to-all

Add a task ID for all the tasks on the page. Update the linked page, if any.

Function: planner-id-search-id id

Search for all occurrences of id.

Function: planner-id-follow-id-at-point

Display a list of all pages containing the ID at point.

Function: planner-id-follow-id-at-mouse event

Display a list of all pages containing the ID at mouse. event is the mouse event.

7.9 Note Indices

Make sure that `planner-notes-index.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-notes-index)

Then you can use tags of the form:

<planner-notes-index page="2004.03.02">
<planner-notes-index from="2004.03.01" to="2004.03.31">
<planner-notes-index limit="10">
<planner-notes-index page="PlanPage">
<planner-notes-index-month-table month="2004.03" limit="5">
<planner-notes-index-month-table month="2004.03">

You can also use the following interactive functions:

planner-notes-index planner-notes-index-days planner-notes-index-weeks planner-notes-index-months planner-notes-index-years (wow!)

These work based on the current date (date of current buffer, or today).

If a single page is specified, this page is scanned for headlines of the form:

 .#1 Headline

The results are presented as a bulleted list.

If from and to are specified, all date pages between them (inclusive) are scanned. If from is omitted, it is assumed to be the earliest entry. If to is omitted, it is assumed to be the latest entry.

If recent is specified, the list includes only that many recent headlines. and the results are presented as a bulleted list.

To customize presentation, you can write a function that generates the appropriate <planner-notes-index> tags. You can also use planner-extract-note-headlines in your own functions.

The following interactive functions are defined in `planner-notes-index.el':

Function: planner-notes-index &optional from to limit

Display a clickable notes index. If called from a Lisp program, display only dates between from and to. With a prefix arg limit, display only that number of entries.

Function: planner-notes-index-days days

Display an index of notes posted over the past few days. The list ends with the day of the current buffer or planner-today.

Function: planner-notes-index-weeks weeks

Display an index of notes posted over the past few weeks. The list ends with the week of the current buffer or planner-today. Weeks start from Sunday.

Function: planner-notes-index-months months

Display an index of notes posted over the past few months. The list ends with the month of the current buffer or planner-today.

Function: planner-notes-index-years years

Display an index of notes posted over the past few years. The current year is included.

`planner-notes-index.el' does not define any keybindings.

7.10 Cyclic Tasks

Make sure that `planner-cyclic.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-cyclic)

Create a diary file named `~/.diary.cyclic-tasks' (or the value of planner-cyclic-diary-file). Here is an example:

Tuesday #B0 _ Study Japanese
Friday #B0 _ Study Japanese (JapaneseStudies)

The first will be a plain task, the second will be linked.

By default, planner-cyclic creates multiple tasks if you let tasks build up (that is, the next Tuesday rolls around and you still haven't marked the task as done.) To turn off this behavior:

(setq planner-cyclic-diary-nag nil)

`planner-cyclic-diary' includes the following interactive functions:

Function: planner-cyclic-create-tasks-maybe

Maybe create cyclic tasks. This will only create tasks for future dates or today.

`planner-cyclic.el' does not define any keybindings.

7.11 RSS Publication

`planner-rss.el' allows you to publish your notes in the RSS 2.0 XML format for blog syndication. You will also want to customize the following variables:

User Option: planner-rss-base-url

Base absolute URL for published blog entries. Should include trailing `/'.

User Option: planner-rss-category-feeds

Rules for automatic categorization of posts and publishing to RSS files. A blog entry is matched against each condition. If it matches the regular expression or the function returns a non-nil value, the blog entry is copied into the specified file.

User Option: planner-rss-feed-limits

A list of regular expressions that match feed filenames and the size and item limits for feeds that match. For example, you can use `(("." nil 10))' to ensure that all feeds are limited to the 10 most recent items.

To manually add the current note to all the matching RSS feeds, invoke planner-rss-add-note. You can specify a filename with the universal prefix, like this: C-u M-x planner-rss-add-note.

If you use the `remember-planner.el' module to create notes, you can automatically publish new notes to RSS feeds by adding the following code to your `.emacs' (or `_emacs').

(add-to-list 'remember-planner-append-hook 'planner-rss-add-note t)

`planner-rss.el' defines the following interactive functions:

Function: planner-rss-add-note feed

Export the current note using planner-add-item. If feed is specified, add the entry to the specified file. Else, add the entry to all matching RSS feeds specified by planner-rss-category-feeds.

7.12 RDF Publication

Put planner-rdf.el in a directory that is in your Emacs load-path and the following into your ~/.emacs file:

(require 'planner-rdf)
(add-hook 'emacs-wiki-after-file-publish-hook
          'planner-rdf-publish-file)
(add-hook 'emacs-wiki-after-wiki-publish-hook
          'planner-rdf-publish-index)

7.12.1 Publishing with planner-rdf

Planner-rdf is now included in the normal Planner publishing process. Pressing C-p will create a .owl and a .rdf file for every planner file. Additionally it creates an index, `index.rdf'.

By default all generated files will be stored in the normal Planner publishing directory, where the HTML files end up. If you would ike to change that, set the variable planner-rdf-directory to the desired location.

The generated files:

• `index.rdf' - a collection with pointers to the `<plan-page>.rdf' files.
• `<plan-page>.rdf' - contains Dublin Core metadata about the files related to the current Planner page. Currently it contains metadata about the source file, the Emacs plan page, the generated HTML page, and the generated OWL file.
• `<plan-page>.owl' - contains task and note data from the Planner file. Task information is stored completely. For notes, the note headline is stored.

7.12.2 planner-rdf Tags

Besides the factual information, e.g. the task status or description, planner-rdf extracts links (in the format `[[...][...]]' or `[[...]]') and tags (`{{...:...'}}) from tasks and notes (including the notes text). Links and tags provide context for the plan elements and so are stored and linked with the containing elements.

Links point to locations that can be used to enrich the information in the Planner pages (e.g, by retrieving data from them and adding it), tags -- like the one for the task ids `{{Tasks:198}}' -- can be used to express abstract qualities. Some examples:

• an `{{audience:myteam}}' tag, can be used to restrict publishing of items to a certain user group;
• a `{{lang:de}}' tag, signifying the language of the text;
• a `{{location:Hamburg}}' tag, can be used to make geographic reference to an entity that is not stored in your address book, bbdb.

What tags to use is up to the user. Planner-rdf makes no assumptions about them, it just extracts and stores them. Only the applications using the data know what to do with them.

7.12.3 Usage Examples

Report generation with OpenOffice

The Perl file `this-week.pl' (http://www.rainervolz.de/planner-rdf/this-week.pl) creates a simple report for the current week. The script extracts task and note information from the generated OWL files and inserts it into a simple OpenOffice Writer document. Nothing fancy, just a proof of concept, to show how planner-rdf can be used to integrate Planner Mode with other applications.

Besides Perl and OpenOffice you'll need the Redland RDF Application Framework (http://www.redland.opensource.ac.uk/). It is used to process the RDF data. Redland is small, but powerful, and available for many platforms and languages.

As an example the application loads the RDF data each time it is run. In the real world you probably would use Redland to store the Planner data in a database, to save the loading step each time you access the data.

Importing Planner data into Protege

Protege is a popular ontology editor and knowledge management application. A simple way to import data into it, is to provide a OWL file that contains the data as well as the schema. To do this:

• Use `planner2protege.pl' (http://www.rainervolz.de/planner-rdf/planner2protege.pl) to combine all OWL files into a single one.
• Use CWM (http://www.w3.org/2000/10/swap/doc/cwm.html) to combine schema and data, with python cmw --rdf planner-rdf.owl planner-data.owl --think --rdf >planner2.owl

Not the most straightforward process, but it works. The resulting file, here planner2.owl, can then be loaded into Protege.

7.13 Experimental Functions

These functions are experimental. This means that they may not do exactly what you expect them to do, so keep backups, be careful, and don't blame us.

To use these functions, make sure that `planner-experimental.el' is in your load path, and add this to your `.emacs' (or `_emacs'):

(require 'planner-experimental)

`planner-experimental.el' defines the following interactive functions:

Function: planner-update-note

Copy the text from this note to the linked note, if any.

Function: planner-search-notes-next-match

Jump to the next matching entry. Call after planner-search-notes.

Function: planner-search-notes-previous-match

Jump to the previous matching entry. Call after planner-search-notes.

Function: planner-remove-duplicates

Remove duplicate tasks.

Function: planner-index

Display an index of all known Wiki pages.

`planner-experimental.el' does not define any keybindings.

8. Integrating with Other Emacs Modules

8.1 Rmail

This module supports links from any kind of Unix mailbox (mbox). To use this module, make sure that `planner-unix-mail.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-unix-mail)

Unix mail URLs are of the form:

;; mail://PATH/TO/INBOX/message-id

Annotations will be of the form:

[[mail://PATH/TO/INBOX/E1AyTpt-0000JR-LU%40sacha.ateneo.edu][E-mail from Sacha Chua]]

`planner-unix-mail.el' does not define any interactive functions or create any new keybindings.

8.2 Gnus

To use this module, make sure that it is in your load path and put this in your `.emacs' (or `_emacs'):

(require 'planner-gnus)
(planner-gnus-insinuate)

With this module loaded, when you create tasks from Gnus summary or message buffers, the tasks will be annotated with information from the message you were looking at when you created each task. A link will also be created on your planner page that you can select in order to return to the message.

So, the created task will look something like this:

#A34 _ Send writing to publishme.com from
[[gnus://alt.books.beatgeneration/<Ifo5c.24632$F9.9567@nwrddc01.gnilink.net>][E-Mail
from editor@verizon.net]] {{Tasks:71}} ([[Writing]])

This module also binds the key n in the Gnus summary view to the command to create a new task.

`planner-gnus.el' does not define any interactive functions.

For more information about Gnus, see section `Top' in The Gnus Newsreader.

8.3 VM

To use this module, make sure that `planner-vm.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-vm)

VM URLs are of the form:

vm://path/to/inbox/message-id

Annotations will be of the form:

[[vm://home/test/INBOX/<E1AyTpt-0000JR-LU@sacha.ateneo.edu>][E-mail from Sacha Chua]]

`planner-vm.el' does not define any interactive functions or keybindings.

8.4 Wanderlust

To use this module, make sure that `planner-wl.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-wl)

Then, when you call M-x planner-create-task-from-buffer from Wanderlust summary or message buffers, the task will be created with the correct annotation.

`planner-wl' does not define any interactive functions.

To add keybindings to Wanderlust, call:

(planner-wl-insinuate)

This binds F to planner-create-task-from-buffer.

8.5 MH-E

To use this module, make sure that `planner-mhe.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-mhe)

Then, when you call M-x planner-create-task-from-buffer from MH-E summary or message buffers, the task will be created with the correct annotation.

`planner-mhe' does not define any interactive functions.

8.6 Rmail

To use this module, make sure that `planner-rmail.el' is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-rmail)

Rmail URLs are of the form:

rmail://message-id

Annotations will be of the form:

[[rmail://<E1AyTpt-0000JR-LU@sacha.ateneo.edu>][E-mail from Sacha Chua]]

`planner-rmail.el' does not define any interactive functions or create any new keybindings.

For more information about Rmail, see section `Rmail' in GNU Emacs Manual.

8.7 Diary

If you use Emacs's diary feature (see section `Diary' in GNU Emacs Manual), Planner-Diary could be helpful for you. It puts all diary entries for the current day in the `* Diary' section of your day plan page. This section is updated every time you display the file in Emacs. By default the diary section of past pages is not updated (it's pretty unlikely that you want to add new diary entries for the past).

If you want to use `planner-diary.el', make sure the file is in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-diary)

`planner-diary.el' needs fancy-diary-display. To use fancy-diary-display, add this to your `.emacs' (or `_emacs'):

(add-hook 'diary-display-hook 'fancy-diary-display)

You can use Planner-Diary in two different ways:

1. You can put the following line of Lisp code in your day plan pages to display your diary entries:

   <lisp>(planner-diary-entries-here)</lisp>

   You can do this automatically for all day plan pages:

   (setq planner-day-page-template "* Tasks\n\n\n* Diary\n\n<lisp>(planner-diary-entries-here)</lisp>\n\n* Notes")

   When you open a day plan page outside Emacs, you will see the line of Lisp code and not your diary entries.

2. If you want the saved files to contain your entries and not just a line of Lisp, add the following lines to your `.emacs' (or `_emacs'):

   (setq planner-diary-use-diary t) (planner-diary-insinuate)

   You should also customize or set planner-day-page-template to include a `* Diary':

   (setq planner-day-page-template "* Tasks\n\n\n* Schedule\n\n\n* Diary\n\n\n* Notes")

C-c C-e updates the diary sections. C-u C-c C-e forces an update--it inserts the diary section for the day, even if the day is in the past or if there is no `Diary' section in the buffer.

If you want to see your diary entries for more than just one day, set planner-diary-number-of-diary-entries accordingly. This works for either of the two approaches.

If you want to use the Cal-Desk package, simply follow the instructions in `cal-desk.el'. If you get the Cal-Desk layout from the Calendar buffer, you get it in the day plan buffer, too.

If you use Planner-Diary, you might consider using the Calendar (see section `Calendar/Diary' in GNU Emacs Manual) support of PlannerMode. To get Calendar integration, add this to your `.emacs' (or `_emacs'):

(planner-insinuate-calendar)

If planner-diary-create-section-flag is non-nil, sections are always inserted if necessary.

User Option: planner-diary-create-section-flag

Non-nil means create the requested diary sections if they do not exist. By default, planner-diary tries to create the section. If you want more control over your pages, you can set this to nil. Trying to write a diary section to a page that does not have it yet will then result in an error.

`planner-diary.el' defines the following interactive functions:

Function: planner-diary-insert-diary force

Insert the fancy diary for the day into the day plan file. If force is non-nil, insert a diary section even if there is no planner-diary-string in the buffer.

Function: planner-diary-insert-diary-maybe force

Maybe insert the fancy diary for the day into the day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a diary section even if there is no planner-diary-string in the buffer.

Function: planner-diary-insert-appts force

Insert the diary appointments for the day into the day plan file. If force is non-nil, insert a diary appointments section even if there is no planner-diary-appts-string in the buffer.

Function: planner-diary-insert-appts-maybe force

Maybe insert the diary appointments for the day into the day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a diary appointments section even if there is no planner-diary-appts-string in the buffer.

Function: planner-diary-insert-cal-desk force

Insert the cal-desk diary for the day into the day plan file. If force is non-nil, insert a cal-desk diary section even if there is no planner-diary-cal-desk-string in the buffer.

Function: planner-diary-insert-cal-desk-maybe force

Maybe insert the cal-desk diary for the day into the day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a cal-desk appointments section even if there is no planner-diary-cal-desk-string in the buffer.

Function: planner-diary-insert-public force

Insert the public diary for the day into the day plan file. If force is non-nil, insert a public diary section even if there is no planner-diary-public-string in the buffer.

Function: planner-diary-insert-public-maybe force

Maybe insert the public diary for the day into the day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a public appointments section even if there is no planner-diary-public-string in the buffer.

Function: planner-diary-insert-private force

Insert the private diary for the day into the day plan file. If force is non-nil, insert a private diary section even if there is no planner-diary-private-string in the buffer.

Function: planner-diary-insert-private-maybe force

Maybe insert the private diary for the day into the day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a private appointments section even if there is no planner-diary-private-string in the buffer.

Function: planner-diary-insert-all-diaries force

Update all diary sections in a day plan file. If force is non-nil, insert a diary section even if there is no section header. It only inserts diaries if the corresponding planner-diary-use-* variable is `t'.

Function: planner-diary-insert-all-diaries-maybe force

Update all diary sections in a day plan file. If the current day is in the past and force is nil, don't do anything. If force is non-nil, insert a diary section even if there is no section header. It only inserts diaries if the corresponding planner-diary-use-* variable is `t'.

Function: planner-diary-show-day-plan-or-diary

Show the day plan or diary entries for the date under point in calendar. Add this to calendar-move-hook if you want to use it. In that case, you should also remove-hook `planner-calendar-show' from calendar-move-hook.

`planner-diary.el' adds the following keybinding to PlannerMode, if planner-diary-insinuate is in your `.emacs' (or `_emacs'):

• C-c C-e updates the diary sections.

8.7.1 Planner-Diary Advanced Features

The features described here are part of the development version. They are subject to change without notice. They may be buggy. The documentation may be inaccurate. Use at your own risk.

There is a lot of code redundancy in the development version. This is intentional and makes it easier to change the code for one type of diary section without breaking others.

Currently Planner-Diary supports six different views of your diary entries:

1. Ordinary fancy diary display (what you get by pressing d in the calendar buffer with fancy-diary-display switched on)

2. Schedule/Appointments (all entries from 1 that have a time assigned to them

3. Diary without appts (1 without 2)

4. cal-desk display (appts on top, non appts entries at bottom)

5. A private diary (same as 1, but uses a different diary-file)

6. A public diary (same as 1, but uses a different diary-file)

Put the following line of Lisp code in you day plan pages to display your diary entries:

<lisp>(planner-diary-entries-here)</lisp>

The function planner-diary-entries-here takes two optional arguments--the diary file you want to use and the number of days you want to display.

8.8 Ledger

`planner-ledger.el' provides integration between planner and John Wiegley's ledger accounting program, which can be found at http://newartisans.com/johnw/ledger.tar.gz.

To use planner-ledger to insert a ledger balance overview and a list of pending transactions into planner day pages, make sure that your day page includes sections that match planner-ledger-balance-regexp and planner-ledger-pending-regexp. Example:

* Tasks

* Ledger

** Pending transactions

* Notes

You can manually update ledger sections with the following command:

Function: planner-ledger-insert-maybe

Update any ledger sections on the current page.

You can also automatically update ledger sections with the following hook:

(add-hook 'planner-goto-hook 'planner-ledger-insert-maybe)

You can create ledger entries from specially-formatted tasks using planner-ledger-add-entry-from-task. Tasks should be of the form `payment due: payee, amount [comment]'. Example:

#A1 _ payment due: foobar, $1000.00 some comment here
#A2 _ payment due: baz, 1000.00

Function: planner-ledger-add-entry-from-task

Create a ledger entry based on the task at point. Task should match planner-ledger-payment-task-regexp.

User Option: planner-ledger-balance-accounts

List of accounts to be included or excluded from the balance overview. `+' includes all matching accounts, and `-' excludes matching accounts. See the documentation for ledger-run-ledger for more details.

User Option: planner-ledger-balance-regexp

Regular expression matching section for ledger balance. Do not store other data in this section, as it will be overwritten.

User Option: planner-ledger-pending-regexp

Regular expression matching section for ledger balance. Do not store other data in this section, as it will be overwritten.

User Option: planner-ledger-payment-task-regexp

Regular expression matching special ledger tasks.

8.9 BBDB

`planner-bbdb.el' allows you to refer to your contacts easily from within a planner page. See Info file `bbdb', node `Top'.

`[[bbdb://Sacha.*Chua][Sacha]]', for example, will be linked to the blog, web or net fields of the first matching BBDB record.

`planner-bbdb.el' does not define any interactive functions, or keybindings.

8.10 Emacs Relay Chat

To use planner-erc, place `planner-erc.el' in your load path and add this to your `.emacs' (or `_emacs'):

(require 'planner-erc)

ERC URLs are of the form, `erc://server/nick/channel', `erc://server/nick' or `erc://server/nick'.

Annotations will be of the form:

[[erc://server/nick/#channel][Chat with nick on server#channel]]
[[erc://server/nick][Chat with nick on server]]
[[erc://server][Chat on server]]

`planner-erc.el' does not define any interactive functions, or keybindings.

8.11 W3m

This module allows you to create tasks from a w3m buffer.

`planner-w3m.el' does not define any interactive functions, or keybindings.

8.12 Schedule

`planner-schedule.el' allows you to project task completion time. Tasks should be of the form:

#A0 _ 2h Do something
#B0 _ 1h30m Do something
#B0 _ 2d Do something
#B0 _ 2w Do something
#B0 _ 10s Do something

s: seconds, m: minutes, h: hours, d: days, w: weeks

You can get `schedule.el' from http:// www.newartisans.com/ johnw/ Emacs/ schedule.el

`planner-schedule.el' defines the following interactive functions:

Function: planner-schedule-show-end-project

Display the estimated project completion time.

`planner-schedule.el' defines the following keybindings:

C-c RET is bound to planner-schedule-show-end-project. C-c C-m is also bound to planner-schedule-show-end-project.

In Xemacs, planner-schedule-show-end-project is bound to C-c C-T c-e and C-c C-S-t C-e.

`schedule.el' provides a single Lisp function, schedule-completion-time. It takes an Emacs time object and a quantity of seconds. It returns an Emacs time object that represents when the given number of seconds will be completed, assuming that work can only be done during work hours.

The available work hours are affected by several factors:

1. If `timeclock.el' is being used, the amount of time left in the current work day (timeclock-workday-remaining) (see section `Time Intervals' in GNU Emacs Manual)

2. The amount of time in each work day (schedule-workday)

3. The definition of a work week (schedule-week)

4. Any holidays defined in the Emacs calendar (see section `Holidays' in GNU Emacs Manual)

5. Any appointments in the Emacs diary (see section `Appointments' in GNU Emacs Manual)

Taking all of the "block out" periods into account, schedule-completion-time will compute when the given number of seconds will be done, based on your current definitions of time available.

As an example, here's a function which, given a list of durations in seconds, will return a list of completion times starting from the current moment:

  (defun compute-completion-times (&rest durations)
    ``Compute completion times for a list of DURATIONS (in seconds).''
    (let ((now (current-time)))
      (mapcar
       (function
        (lambda (dura)
          (setq now (schedule-completion-time now dura))))
       durations)))

To call this function, do:

(compute-completion-times 3600 7200 3600)

`schedule.el' does not define any interactive functions, or keybindings.

8.13 Timeclock

This module allows you to clock in and clock out of your projects (see section `Time Intervals' in GNU Emacs Manual). You can also generate reports with the <timeclock-report> tag.

With `planner-timeclock.el' loaded, planner-task-in-progress clocks in a task. To clock out, use planner-task-done or timeclock-out.

`planner-timeclock.el' defines the following keybindings:

• C-c C-i: planner-task-in-progress.
• C-c C-o: timeclock-out.
• C-c C-T C-i: planner-timeclock-in. (XEmacs)
• C-c C-T C-o: timeclock-out. (XEmacs)
• C-c C-S-t C-i: planner-timeclock-in. (GNU Emacs)
• C-c C-S-t C-o: timeclock-out. (GNU Emacs)

If you use timeclock a lot, you may also be interested in Dryice Liu's `planner-timeclock-summary.el', which produces timeclock reports for planner files.

To load it, add (require 'planner-timeclock-summary) to your `~/.emacs'. You can then use it in two ways.

• Display a temporary buffer

  Call planner-timeclock-summary-show and Emacs will ask you which day's summary do you want. Choose the date as anywhere else of Emacs planner, and a tempory buffer will be displayed with the timeclock summary of that day.

• Rewrite sections of your planner

  Choose this approach if you want timeclock summary to be in their own section and you would like them to be readable in your plain text files even outside Emacs. Caveat: The timeclock summary section should already exist in your template and will be rewritten when updated. Tip: Add planner-timeclock-summary-section (default: `"Timeclock"') to your planner-day-page-template.

  To use, call planner-timeclock-summary-update in the planner day page to update the section. If you want rewriting to be automatically performed, call planner-timeclock-summary-insinuate in your .emacs file

8.14 planner-log-edit.el

This module allows you to automatically record CVS (and VC) commits in today's page.

You can load the module with (require 'planner-log-edit). When you load the module, planner-log-edit-add-note will be added to log-edit-done-hook. A note containing the text of the commit and optionally a list of modified files will be added to today's page if you use the the Emacs version control interface. (see section `Version Control' in GNU Emacs Manual)

User Option: planner-log-edit-include-files-flag

Non-nil means include a list of committed files in the note.

User Option: planner-log-edit-notice-commit-function

Non-nil means include a list of committed files in the note. If you want to enable this feature for some projects but not for others, set this to a function that returns t only for the commits you want to note.

`planner-log-edit.el' does not define any interactive functions.

8.15 planner-bibtex.el

BibTeX URLs are of the form `bibtex://file/name:key'.

`planner-bibtex.el' does not define any interactive functions.

9. Advanced Configuration

9.1 Customizing Your Day Pages

With the variable planner-day-page-template, you can define how you want any newly created day planner pages to look.

You might want to include a section for your diary entries. For how to do this, see 8.7 Diary.

You can add interactive Lisp buttons with the `planner-lisp.el' module. (see section 7.3 Interactive Lisp with planner-lisp.el)

Your planner-day-page-template can also include any Emacs-Wiki tags.

For more complex day pages, you can set planner-day-page-template to a function that will be called from an empty day page buffer. The function should initialize the contents of the day page.

9.2 Variables to Customize

If you want to change planner-directory and some other variables, either use Customize (M-x customize-group RET planner RET) or use planner-option-customized. For example:

(planner-option-customized 'planner-directory "~/Plans")
  (planner-option-customized 'planner-publishing-directory
                              "~/public_html/plans")

If you want to modify other Emacs-Wiki variables, do:

   (add-to-list 'planner-custom-variables
                '(some-emacs-wiki-variable . "some-emacs-wiki-value"))
   (planner-option-customized 'planner-custom-variables
                              planner-custom-variables)

See emacs-wiki-update-project and planner-custom-variables for more details.

Other user options are:

User Option: planner-use-day-pages

If you really don't like day pages, you can set this variable to nil and you won't be prompted for dates for tasks and notes.

User Option: planner-mode-hook

List of functions to run after planner-mode is initialized.

User Option: planner-tasks-file-behavior

This variable controls what happens to files Planner opens by itself. If your tasks are associated with plan pages, the plan pages are updated whenever a task is rescheduled. This could lead to a lot of open buffers as Planner applies updates to all linked files. By default, Planner is configured to do nothing. A value of `save' means save but do not close buffers, and a value of `nil' means do not save any of the buffers.

User Option: planner-add-task-at-end-flag

This variable controls where new tasks are created. Non-nil means create tasks at the bottom of the first task block. If you set this to non-nil, new tasks will be listed in order of creation (oldest). Tasks carried over from previous days will appear at the bottom of the list.

Nil means create tasks at the top of the first task block. Carried-over tasks and newly created tasks are prominently placed on top of the list of tasks for the day.

User Option: planner-default-page

Default page for created tasks. This is used as the initial value for tasks. After you create a task, it will be set to the previous page used.

User Option: planner-hide-task-status-when-highlighting

Font-locking for tasks may be enough for you to determine status and priority. Set this to non-nil if you want to hide the status marker and rely on font-locking instead.

User Option: planner-create-task-hook

Functions run after creating a task. planner-id hooks into this.

User Option: planner-expand-name-favor-future-p

If non-nil, partial dates (ex: 2 or 5.2) are completed to dates in the future instead of using the current year and month.

User Option: planner-task-dates-favor-future-p

Like planner-expand-name-favor-future-p, but only for tasks.

9.3 Ideas for Other Keybindings

By default and for backward compatibility, the following operations do not have keybindings, and are only accessible from the Planner menu:

• planner-copy-or-move-region

• planner-delete-task

• planner-task-delegated

• planner-task-pending

• planner-task-open

• planner-renumber-tasks

You may find it easier to install keybindings for those operations by inserting the following in your `.emacs' (or `_emacs'). Note: This changes some of the default keybindings for PlannerMode.

(planner-install-extra-task-keybindings)

If you install the extra task keybindings, your keybindings will include:

• C-c C-t will be unbound from the default and will serve as the prefix for the other task keybindings.

• C-c C-t C-t: planner-create-task-from-buffer.

• C-c C-t C-k: planner-delete-task.

• C-c C-t C-u: planner-update-task.

• C-c C-t C-c: planner-copy-or-move-task.

• C-c C-t C-S-c: planner-copy-or-move-region.

• C-c C-t C-x: planner-task-done.

• C-c C-t C-S-x: planner-task-cancelled.

• C-c C-t C-d: planner-task-delegated.

• C-c C-t C-p: planner-task-pending.

• C-c C-t C-o: planner-task-in-progress.

• C-c C-t C-r: planner-raise-task.

• C-c C-t C-l: planner-lower-task.

• C-c C-t C-n: planner-renumber-tasks.

Other keybindings can be configured by adding this to your `.emacs' (or `_emacs'):

(planner-install-extra-context-keybindings)

This will set up the following keybindings:

• shift up planner-move-up

• shift down planner-move-down

• shift right planner-jump-to-link

10. Reference Material

10.1 Other Interactive Functions

With `planner.el' loaded, you can use any of the functions in this section by typing M-x followed by the name of the function. Many of these functions are also bound to keys.

For a list of PlannerMode keybindings, see 10.2 PlannerMode Keybindings.

They are listed in no particular order.

`planner.el' defines the following interactive functions:

Function: planner-create-high-priority-task-from-buffer

Create a high priority task based on this buffer. Do not use this in LISP programs. Instead, set the value of planner-default-task-priority and call planner-create-task or planner-create-task-from-buffer.

Function: defun planner-create-medium-priority-task-from-buffer

Create a medium-priority task based on this buffer. Do not use this in LISP programs. Instead, set the value of planner-default-task-priority and call planner-create-task or planner-create-task-from-buffer.

Function: planner-create-low-priority-task-from-buffer

Create a high-priority task based on this buffer. Do not use this in LISP programs. Instead, set the value of planner-default-task-priority and call planner-create-task or planner-create-task-from-buffer.

Function: planner-install-extra-context-keybindings

Install extra context-sensitive keybindings. These keybindings conflict with `windmove.el', but might be useful.

Function: planner-narrow-to-section section

Widen to the whole page and narrow to the section labelled section. Return non-nil if section was found.

Function: planner-save-buffers

Save all planner-mode buffers.

Function: planner-seek-to-first section

Positions the point at the specified section, or `Tasks' if not specified.

Function: planner-save-buffers

Save all planner buffers.

Function: planner-calendar-insinuate

This hooks PlannerMode into Emacs Calendar (see section `Calendar/Diary' in GNU Emacs Manual).

It adds special planner key bindings to calendar-mode-map. After this function is evaluated, you can use the following planner-related keybindings in calendar-mode-map:

n

Jump to the planner page for the current day.

N

Display the planner page for the current day.

Function: planner-kill-calendar-files

Remove planner files shown from Calendar (see section `Calendar/Diary' in GNU Emacs Manual).

Function: planner-calendar-goto

Goto the plan page corresponding to the calendar date (see section `Calendar/Diary' in GNU Emacs Manual).

Function: planner-calendar-show

Show the plan page for the calendar date under point in another window (see section `Calendar/Diary' in GNU Emacs Manual).

Function: planner-calendar-select

Return to planner-read-date with the date currently selected (see section `Calendar/Diary' in GNU Emacs Manual).

Function: planner-jump-to-link

Jump to the item linked to by the current item.

Function: planner-move-up

Move up. On a task, raise the priority of the current task. On a note, go to the previous note. On a headline, go to the previous headline of the same depth.

Function: planner-move-down

Move down. On a task, lower the priority of the current task. On a note, go to the next note. On a headline, go to the next headline of the same depth.

10.2 PlannerMode Keybindings

In order to refresh and renumber all of your tasks according to their actual order in the buffer, simply save the file or call M-x planner-renumber-tasks.

Here is a summary of the keystrokes available:

M-x plan

Begin your planning session. This goes to the last day for which there is any planning info (or today if none), allowing you to review, and create/move tasks from that day.

C-c C-u

Raise a task's priority.

C-c C-d

Lower a task's priority.

C-c C-s

Mark the task as in progress or delegated.

C-c C-x

Mark the task as finished.

C-c C-t

Create a task associated with the current Wiki page. If you are on the opening line of a Note entry, it is assumed that the note itself is the origin of the task.

C-c C-c

Move or copy the current task to another date. If the current task is an original (meaning you are in the buffer where's defined, hopefully a planning page) then it will be copied, and the original task will also now point to the copy. If the current task is a copy, it will just be moved to the new day, and the original task's link will be updated.

C-c C-n

Jump to today's task page. If you call (planner-calendar-insinuate), typing n in the Emacs calendar (see section `Calendar/Diary' in GNU Emacs Manual) will jump to today's task page.

C-c C-x

planner-task-done

C-c C-z

planner-task-in-progress

C-c C-d

planner-lower-task

C-c C-u

planner-raise-task

C-c C-c

planner-copy-or-move-task

C-c C-t

planner-create-task-from-buffer

C-c C-j

This is a prefix command.

C-c C-n

planner-goto-today

C-c C-j C-r

planner-goto-most-recent

C-c C-j C-t

planner-goto-tomorrow

C-c C-j C-y

planner-goto-yesterday

C-c C-j C-j

planner-goto-today

C-c C-j C-n

planner-goto-next-daily-page

C-c C-j C-p

planner-goto-previous-daily-page

C-c C-j C-d

planner-goto

10.3 Sample Configuration Files

In this section, I've included some sample configuration files. This way, once you've got the hang of the basics, you can see some different, more advanced, setups.

10.3.1 Sacha Chua Configuration

;;; Sacha's configuration for planner.el
;; Sacha Chua <sacha@free.net.ph>

;;;_+ Loading

;; This directory contains all the latest emacs-wiki and planner files.
(add-to-list 'load-path "~/notebook/emacs/planner-dev")

(require 'planner)
(require 'planner-experimental)
(require 'planner-bbdb)
(require 'planner-notes-index)
(require 'planner-diary)
(require 'planner-gnus)
(require 'planner-erc)
(require 'planner-id)
;; (require 'planner-notes)
(require 'planner-rss)
;; (require 'planner-schedule)
;; (require 'planner-timeclock)
(require 'planner-w3m)
(planner-use-muse-backend)

;; (planner-insinuate-calendar)
(load "remember-config")

;;;_+ Font lock

(unless (listp font-lock-support-mode)
  (setq font-lock-support-mode (cons t font-lock-support-mode)))
(add-to-list 'font-lock-support-mode '(planner-mode . nil))
(add-to-list 'font-lock-support-mode '(planner-muse-mode . nil))
(add-to-list 'font-lock-support-mode '(planner-emacs-wiki-mode . nil))

;;;_+ Basic setup

(setq planner-directory "/home/sacha/notebook/plans")
(setq planner-carry-tasks-forward t)
(setq planner-expand-name-favor-future-p t)
(setq planner-publishing-directory "/home/sacha/public_html/notebook/wiki")

(setq planner-emacs-wiki-custom-variables
      '((emacs-wiki-publishing-header . "<lisp>(my-publishing-header)</lisp>")
	(emacs-wiki-publishing-footer . "<lisp>(my-publishing-footer)</lisp>")
	(emacs-wiki-publishing-file-suffix . ".php")))
(setq planner-day-page-template
      "<contents>\n\n* Tasks\n\n\n* ~/.diary schedule\n\n* Notes\n\n")
(setq planner-diary-string "* ~/.diary schedule")

;;; Compatibility, purely for old pages I'm too lazy to change.
;;; planner-diary is so much cooler.

(defun sacha/planner-get-diary-entries (date)
  "For DATE (yyyy.mm.dd), return a list of diary entries as a string."
  (require 'diary-lib)
  (when (string-match planner-date-regexp date)
    (let* ((diary-display-hook 'ignore)
           (entries (list-diary-entries
                     (list (string-to-number (match-string 2 date)) ; month
                           (string-to-number (match-string 3 date)) ; day
                           (string-to-number (match-string 1 date))) ; year
                     1))) ; Get entries for one day
      (if entries
          (mapconcat (lambda (item) (nth 1 item)) entries "\n")
        nil))))

(fset 'planner-get-diary-entries 'sacha/planner-get-diary-entries)

;;; Here we use planner-diary.
(planner-diary-insinuate)

;;;_+ Header and footer

;;(defvar planner-day-header-file "/home/sacha/notebook/wiki/.day.header"
;;  "The header file to include for planner day pages (ex: 2003.03.17)")
;;(defvar planner-day-footer-file "/home/sacha/notebook/wiki/.day.footer"
;;  "The footer file to include for planner day pages (ex: 2003.03.17)")
(defvar planner-header-file "/home/sacha/notebook/wiki/.header"
  "The header file to include for normal planner pages (ex: WelcomePage)")
(defvar planner-footer-file "/home/sacha/notebook/wiki/.footer"
  "The footer file to include for normal planner pages (ex: WelcomePage)")


(defvar sacha/planner-no-header-or-footer
  '("SideBar"))

(defun my-publishing-header ()
  "Insert the header only if this file should have it."
  (cond
   ((member (emacs-wiki-page-name) sacha/planner-no-header-or-footer) "")
   ((file-readable-p planner-header-file) (ignore (insert-file-contents planner-header-file)))
   (t "this is the default header text, if the file can't be found\n")))
  
(defun my-publishing-footer ()
  "Insert the footer only if this file should have it."
  (cond
   ((member (emacs-wiki-page-name) sacha/planner-no-header-or-footer) "")
   ((file-readable-p planner-footer-file) 
    (ignore (insert-file-contents planner-footer-file)))
   (t "this is the default footer text, if the file can't be found\n")))

;;;_+ Allout

;;(when (load "allout" t)
;;  (add-to-list 'planner-mode-hook (lambda ()
;;				    (condition-case err
;;					(progn
;;					  (allout-mode 1)
;;					  (allout-show-all)
;;					  (auto-fill-mode -1)
;;                                          (setq allout-old-style-prefixes nil))
;;				      (error nil)) t)))

;;;_+ Emacspeak

(defadvice emacs-wiki-next-reference (after emacspeak pre act comp)
  "Provide additional feedback"
  (message "%s" (match-string 0)))
(defadvice emacs-wiki-previous-reference (after emacspeak pre act comp)
  "Provide additional feedback"
  (message "%s" (match-string 0)))

;;;_+ RSS blogging
(add-to-list 'remember-append-to-planner-hook 'planner-rss-add-note t)

(planner-update-project)
;;;_* Local emacs vars.
;;;Local variables:
;;;allout-layout: (* 0 : )
;;;End:

(provide 'planner-config)

;;; planner-config.el ends here

11. Getting Help and Reporting Bugs

After you have read this guide, if you still have questions about PlannerMode, or if you have bugs to report, there are several places you can go.

You can join the mailing list at emacs-wiki-discuss@nongnu.org using the subscription form at http:// mail.nongnu.org/ mailman/ listinfo/ emacs-wiki-discuss. This mailing list is also available via Gmane (http://gmane.org/). The group is called `gmane.emacs.wiki.general'.

You can explore the relevant sections of the EmacsWiki:

• http://www.emacswiki.org/cgi-bin/wiki/PlannerMode

• http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMode

• http://www.emacswiki.org/cgi-bin/wiki/RememberMode

You can visit the IRC Freenode channel `#emacs'. Many of the contributors are frequently around and willing to answer your questions.

There is an Orkut community called PlannerMode.

You can also contact the maintainer of PlannerMode, Sacha Chua, at sacha@free.net.ph.

For questions, bug reports or feature requests regarding Planner-Diary, you can contact Thomas Gehrlein at thomas.gehrlein@t-online.de.

For issues relating to this documentation, please contact John Sullivan at johnsu01@yahoo.com.

12. Contributors

This is an incomplete list of people who have helped out with PlannerMode:

• John Wiegley (johnw@gnu.org)

• Sacha Chua (sacha@free.net.ph)

• Eric Belpaire (Eric.Belpaire@equant.com)

• Damien Elmes (resolve@repose.cx)

• Jody Klymak (jklymak@coas.oregonstate.edu): some documentation for `planner-diary.el'

• Thomas Gehrlein (Thomas.Gehrlein@t-online.de)

• David Forrest (drf5n@mug.sys.virginia.edu)

• Quasi (quasi@kc4.so-net.ne.jp)

• Jason Lewis (jason@dickson.st)

• Oliver Krause (oik@gmx.net)

• Bob Newell (bnewell@chungkuo.org)

• Brent Goodrick (bgoodrick@ipns.com)

• Yvonne Thomson (yvonne@thewatch.net)

• Chris Hall (hall.cj@verizon.net): minor bugfix to the planner-publishing-markup

• Markus Hoenicka (markus.hoenicka@mhoenicka.de): `tasklist.pl'

• David Smith (davidsmith@acm.org): Lots of patches! =)

• Ephrem Christopher Walborn (christopherw@bonitabaygroup.com)

• Martin Morgan (mtmorgan@moscow.com): Better fontlocking

• Frederik Fouvry (fouvry@coli.uni-sb.de): info links and bugfix

These are people whose work contributed specifically to Emacs-Wiki Mode:

• Alex Schroeder (alex AT gnu DOT org), current author of `wiki.el'. His latest version is here: http://www.geocities.com/kensanata/wiki/WikiMode.html.

• Frank Gerhardt (Frank.Gerhardt AT web DOT de), author of the original Wiki-Mode. His latest version is here: http://www.s.netic.de/fg/wiki-mode/wiki.el.

• Thomas Link (t.link AT gmx DOT at).

13. Thoughts

13.1 Planning Based on the Franklin-Covey Approach

This is a slightly edited and updated version of an essay by John Wiegley.

What is planning? It can be a nebulous thing to define. In its essence, however, it is very simple: it's how we achieve our dreams.

Our days are filled with time, and hence with actions, whether they be of a mental or physical sort. But there are two kinds of action: reactive and creative. Reactive action is a response to the environment, a reaction to stimulus. Had we enough instincts to ensure survival, we could live according to this kind of action alone. It is a mode of behavior we share with every living species.

The opposite to reactivity is creativity, when we decide upon a course of action that is a wholly a product of personal choice. We then make decisions as to the steps needed to make this wish a reality. This is planning. Planning is essentially a creative endeavor at every step.

First, create the idea, what you want to achieve. Very short-term ideas do not need much more than thinking about how to do it. But long-term ideas require planning, since the mind cannot contain all of the details.

Second, decide how the idea maps into the circumstances you find yourself in. Some environments will assist your plan, others hinder it. But step by step, identify every barrier to the realization of your idea, and devise a countermeasure to overcome it. Once you've mapped things out from beginning to end, accounting for unknowables as best you can, you now have your plan.

Third is to break the stages of the plan into parts that are not overwhelming in their complexity. It is at during this phase that a plan is turned into task items, each to be accomplished within the span of one day's time. If a task requires several days, break it up further. The smaller it is, the less your mind will recoil from attempting it.

Fourth is to monitor your progress, identifying problems and correcting for them as you go. Some plans start out unachievable, and remain that way indefinitely, due to a simple lack of observation. If nothing is working for you, change it. Otherwise, your plan is merely a well-crafted wish.

Fifth is just to do the work, and be patient. All good plans take a great deal of time, and *cannot* happen immediately. The groundwork must be laid for each step, or else it will rest on an unsecure foundation. If you follow your plan doggedly, applying some time to it each day or week, it will happen. Remember the story of the tortoise and the hare. I've even written a short essay on the necessity of gradual accomplishment, which can be found at http://emacswiki.org/johnw/essays/node2.html.

How can this software help? Computers are ideal for manipulating information, since they allow you to change things without erasing or rewriting. And since all plans change quite a bit during their implementation, a planning program can be very helpful.

Start by adding the following to your `.emacs' (or `_emacs'):

(load "planner")

Now, conceive your idea. I can't believe there's nothing you want from life. More peace, time to enjoy the world, an end to war? Everyone wants something. Search deeply, and you will find countless unhoped wishes lurking therein. Choose one for now, and think on it for a while.

Then open a file (using C-x C-f) within the directory named by planner-directory. Emacs will automatically recognize this file as a planner file. Name the file after your plan, such as `BetterHealth'.

Choose an idea you really want to accomplish. Struggle to differentiate between the things you want because others want them, and the things you want for yourself. It takes quite an effort, and may require a long time before you notice the difference. Many people want to be more healthy to be more attractive, which is an externally driven goal. Unless you really want to accomplish what you envision, the odds are you will fail. Only our own wishes and dreams possess enough personal energy to see themselves to fruition. What happens to many of us is simply that we never become conscious of these dreams: what we love, what we desire most. When I talk to friends, so much of what I hear is things they want because they feel they should want them. There's just not enough energy there to pursue a good plan, because nearly all of it is negative energy.

Do you know what you really want? Don't worry, many people don't. It's not a question anyone really wants us to pursue, because often we don't want what others do; it doesn't contribute to the social welfare, and all that nonsense. Somehow we always forget that what's good for the social welfare now, was someone else's crazy dream a hundred years ago. The human aversion to fundamental change is always one's greatest enemy, so don't waste any time getting bitter about it.

For the sake of argument I assume you really do want to be healthier, because you've fallen in love with the ideal of purity, or you understand the connection between your physical self and the world around you, and how this can open up your spirit to desiring more. I assume. :)

So you're in a Wiki file called `BetterHealth'. Start typing. Type anything related to your idea: what you think about it, your ideas on it, and especially what the end will look like. If you can't visualize the end, you can't plan, since planning is about drawing a line between now and then.

When you've typed enough to gain a vision of your goal, start drafting what the possible intermediate steps might be. Then stop, get up, walk around, enjoy life, and come back to it. Taking a long time at the beginning is not a bad idea at all, as long as it's not forever.

As you chew on your idea, it will begin to become more and more concrete. You'll have ideas about the smallest pieces, and ideas about the biggest pieces. Keep going until it starts to take shape before you, and you can see yourself in your mind's eye moving from the present into the future. Write down this progression, and the sorts of things you might encounter along the way.

As you continue, you'll naturally discover discrete phases, or "milestones" as managers love to call them. These are very important, because they let you know you're making progress. I recommend having a big party with friends every time you achieve a milestone. A typical plan might have between three and ten.

Between the milestones are the bigger pieces of your plan. Name these pieces using MixedCase words, and you'll notice that Emacs colors and underlines them for you. Like, FindGoodGym. Hit return on this highlighted word, and you'll find yourself in another, blank file. In this file, start drafting your sub-plan, just as you did with the larger plan. You should find it easier now, since the scope is smaller.

As you break down further, you'll notice simple little things that need to get done. These are your tasks. Every plan is a succession of tasks. The difference from reactivity is that each task is part of the larger plan. This is what it means to be systematic: that everything you do helps further your plan. If you have tasks in your day that contribute to no plan, they are reactive. Of course, life is full of these, but don't let them take up more than 20% of your day. If you allow yourself to be dominated by reactive tasks, you'll regret it at the end of your life. I don't know this personally, but I do know that striving for one's dreams -- and seeing them come to fruition -- is the greatest joy a man can possess. It is the essence of freedom, of living, of creation. Reactivity is the opposite of this, and serves only to drain our energy and slacken our spirits.

Now that you've thought of a simple task, type C-c C-t. This will ask for a brief description of the task, and when you plan to do it. If you hit RETURN at the question `When', it assumes you mean today. It will also pop up a three-month calendar at this question, so you can see where your free days are. Make sure you set the variable mark-diary-entries-in-calendar to `t' in your `.emacs' (or `_emacs') file. This way, you can see which days your appointments fall on. (Read about the Emacs Calendar and Diary in section `Calendar/Diary' in GNU Emacs Manual.)

(setq mark-diary-entries-in-calendar t)

Once your task is in there, go back to your plan and keep generating more tasks. Generate them all! Fully describe--as tasks--everything necessary to bring your sub-plan to completion. Don't create tasks for the other sub-plans. You may have good idea of what they'll look like, but don't bother rendering them into tasks just yet. Things will change too much between now and then, for that to be a good use of your time.

Is your sub-plan now rendered into all of the tasks necessary to reach your first milestone? Great! That is the purpose of planner.el. The rest is really up to you. If you find that you keep putting things off, and never do them, that's the surest sign you're planning for someone else's dream, and not your own.

Here are some of the things planner.el can do, to help you manage and track your tasks:

At the beginning of every day, type M-x plan. This will jump you to the top of the most recent task list before today. If you skipped a bunch of days, you'll have to open up those files on your own.

Probably some of the tasks that day won't be finished -- that's OK. Learning to properly estimate time is a magical, mystical art that few have mastered. Put your cursor on those undone tasks, and type C-c C-c. This will move them into today's task page. You can jump to today's task page at any time by typing C-c C-n (from a Wiki or planning page). I heartily recommend binding C-c n, to jump you to this page from anywhere:

(define-key mode-specific-map [?n] 'planner-goto-today)

As you look at your task sheet each day, the first thing to do is to "clock in" to one of them. This isn't necessary, and is only helpful if you're around your computer a lot. But by typing C-c C-i (assuming you have my `timeclock.el' on your load-path), it will log the time you spend working on your sub-plan (see section `Time Intervals' in GNU Emacs Manual). This is helpful for viewing your progress. Type C-c C-o to clock out.

C-c C-u and C-c C-d will move a task up and down in priority. The priority scheme has two components: a letter A through C, and a number from 1 onwards. 'A' tasks mean they must be done that day, or else your plan is compromised and you will have to replan. 'B' means they should be done that day, to further the plan, otherwise things will be delayed. 'C' means you can put off the task if you need to, although ultimately it will have to be done.

For reactive tasks, the letters mean something different: 'A' means you must do it today, or somebody will roast your chestnuts over an open fire. 'B' means you should do it today, or else someone will be practicing patience at the day's end. 'C' means no one will notice if you don't do it.

Again, reactive tasks are ENEMIES OF PLANNING. Really, until you see them that way, circumstances will push you around and steal your life away. We have only so many years to use, and everyone is greedy to take them. It's insidious, almost invisible. A healthy dislike of reactivity will do wonders for organizing your affairs according to their true priority.

The last word that needs to be said concerns "roles". Every person stands in several positions in his life: husband, employee, manager, etc. These roles will tend to generate tasks not associated with any immediate plan, but necessary to maintain the health and functioning of the role. My suggestion is to keep this the smallest possible number, and fulfill those that remain well. How you decide to apportion your time between pursuing grand designs, and fostering deep relationships, is a personal matter. If you choose well, each will feed the other.

I mention this to point that reactivity is something not exclusively associated with tasks that have no master plan, because being a father, for example, is something that rarely proceeds according to orderly plans. But the role of father itself is its own plan, whose goal is "to be the best one can", and whose component tasks are spending time on whatever comes up. It is, in a sense, an implicit plan. But reactive tasks follow no plan at all; they are parasites of time that suck the spirit away, whereas properly chose roles actually help fulfill one's own inner needs. At least, this is what I believe.

Function: plan force-days

Start your planning for the day, beginning with the last day's tasks.

If planner-carry-tasks-forward is non-nil, find the most recent daily page with unfinished tasks and reschedule those tasks to the current day. If force is non-nil, examine all past daily pages for unfinished tasks.

If planner-carry-tasks-forward is nil, visit the most recent daily page. If a daily page for today exists, visit that instead.

If force-days is a positive integer, scan that number of days. If force-days is `t', scan all days.

13.2 Why Use PlannerMode?

I thought about why I liked PlannerMode. Planner as a TODO manager isn't particularly special. Although I can assign tasks to categories and so see a breakdown of what projects are taking up my time, Evolution and Microsoft Outlook provide more powerful task support. In other task managers, you can e-mail tasks, assign multiple categories and fill in all sorts of metadata. You can even synchronize your tasks with devices like a phone or PDA. So why use Planner?

I realized that integration into my way of life and automatic context clues are what really make planner tasks worth it for me. I don't have to switch to another application to create a task. I can just hit a keyboard shortcut. Planner uses a minibuffer to get the task description. My windows are not rearranged in any way, and I can look at the data that's relevant to a task. Not only that, tasks automatically pick up context clues, like whom I'm talking to on IRC or the file I'm editing at the moment. This cuts down on the explicit context I need to include and makes it easier for me to bring up the task again.

As a scheduler, PlannerMode is also not particularly distinguished. Sure, it can display my `~/diary', but for that matter so can M-x diary. Evolution and Outlook can give me a more graphical view of my time, sync with my PDA, and coordinate my schedule with other people. Those applications support detailed schedule entries with powerful cyclic options. On the other hand, PlannerMode gives me a personal, plain text view and (at least the way I use it) requires me to edit a separate file to add new appointments. However, it does have one advantage--my schedule is always loaded. I used to use Outlook on Windows, but having my schedule in a separate application meant that I actually looked at it very rarely, as I had turned off reminders because they got annoying.

PlannerMode's notes, however, are what really convinced me. I can hit a keyboard shortcut from anywhere and type my notes into a buffer which automatically keeps context information. After typing the note, I can then categorize it. I think that the critical thing here is that interruptions--fleeting thoughts--don't break my flow. I can just pop up a remember buffer, stow that thought away somewhere, and go back to it whenever I want. In contrast, creating a note in Outlook means switching out of my application, making a couple of keystrokes, typing the note in, and then switching back. The context switches make it hard to keep track of where I am and what I'm supposed to remember. Not only that, I need to enter context by hand. Even though I can color my notes and reorganize them in Outlook, I find the context switch too expensive. I used to keep notes in other knowledge management tools as well. Some applications allowed me to drag-and-drop links into the current note, and that was cool. But that required a manual action, and those applications didn't feel integrated into my way of working.

I guess that's why I like PlannerMode. Unlike other organizers which don't know anything about the applications I use, PlannerMode tries its best to integrate into the way I work, and it's easy to extend. Fortunately I do almost all my work in Emacs, so I can think of my organizer as integrated into my e-mail client, Internet Relay Chat client, web browser, file editor and even games. It automatically picks up context clues from these applications and allows me to easily jump back to relevant files. It doesn't distract me. It allows me to key in data and then it gets out of my way.

The processing that happens in the background (publish to RSS and PHP for me) is a bonus, and publishing my task list and notes online has greatly helped me. It gives other people a way to see what I'm working on and what I've planned for the future. Occasionally people write in with additional resources and helpful tips.

A. GNU GENERAL PUBLIC LICENSE

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

A.1 Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

   Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

   You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
   1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

   2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

   3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

   These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

   Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

   In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
   1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

   2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

   3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

   The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

   If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

   If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

   It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

   This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
    NO WARRANTY

12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

A.2 Appendix: How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) yyyy  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

B. GNU Free Documentation License

Copyright © 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

1. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

   This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

   We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

2. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

   A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

   The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

   The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

   A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

   Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

   The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

   A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

   The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

3. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and you may publicly display copies.

4. COPYING IN QUANTITY

   If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

   If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

5. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

   4. Preserve all the copyright notices of the Document.

   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

   8. Include an unaltered copy of this License.

   9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

   11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

   13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

   14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

   15. Preserve any Warranty Disclaimers.

   If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

   You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

6. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

   The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements."

7. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

   You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

8. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

9. TRANSLATION

   Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

   If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

C. ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Index