Merge branch 'master' of ssh://repo.or.cz/srv/git/planner-el

[planner-el.git] / planner-el.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename planner-el.info
@settitle planner-el
@c %**end of header

@dircategory Emacs
@direntry
* planner-el: (planner-el). planner.el: Day planner/organizer for Emacs.
@end direntry

@syncodeindex fn cp

@copying
This manual is for Planner version 3.42.

Copyright @copyright{} 2001, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.@*
Parts copyright @copyright{} 2005 Jim Ottaway@*
Parts copyright @copyright{} 2005 Dryice Dong Liu

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License, Version 3.0
or any later version published by the Free Software Foundation.
A copy of the license is included in the section entitled ``GNU
General Public License.''
@end quotation
@end copying

@titlepage
@title Guide to Planner
@subtitle a day planner and organizer
@subtitle for GNU Emacs and XEmacs

@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c So the toc is printed at the start
@contents

@ifnottex
@node Top, Preface, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top Planner

@insertcopying
@end ifnottex

@menu
* Preface::                     
* Introduction::                
* Installation::                
* Overview::                    A discussion of different approaches to planning
* Getting Started::             
* More about Planner::          In-depth look at some core features
* Managing Your Information::   Integration with external programs
* Advanced Configuration::      
* Reference Material::          
* Getting Help::                
* Acknowledgements::            
* GNU General Public License::  
* Concept Index::               

@detailmenu
 --- The Detailed Node Listing ---

Installation

* Getting the Files::           
* Creating Your Planner::       
* Components::                  
* Advanced Installation::       

Getting the Files

* Installing from a Source Archive::  
* Installing from git::         
* Installing from Debian::      

Overview

* Planning based on the Franklin-Covey Approach::  
* Why Use Planner::             

Getting Started

* Tasks::                       
* Schedule::                    
* Notes::                       
* Hyperlinks::                  
* Example Page::                
* Review::                      

More about Planner

* Navigation::                  
* More about Tasks::            
* More about Notes::            
* Making Files Pretty::         
* Annotations::                 
* Interactive Lisp::            planner-lisp.el
* Publishing::                  planner-publish.el
* Experimental Functions::      planner-experimental.el

More about Tasks

* Creating New Tasks::          
* Organizing Your Tasks::       
* Task Reports and Overviews::  

Creating New Tasks

* Creating a Task::             
* Task Priorities::             
* Task IDs::                    planner-id.el
* Cyclic Tasks::                planner-cyclic.el
* Task Detail::                 
* Deadlines::                   planner-deadline.el

Organizing Your Tasks

* Multiple Projects::           
* Viewing Tasks::               
* Modifying Tasks::             
* Carrying Over Unfinished Tasks::  
* Task Numbering::              
* Task Ranks::                  planner-rank.el
* Grouping Tasks::              planner-trunk.el

Task Reports and Overviews

* Accomplishments::             planner-accomplishments.el
* Status Reports::              planner-report.el
* Task Overviews::              planner-tasks-overview.el
* <tasks> tag::                 
* planner-registry::            Keep track of annotations
* planner-zoom::                View and navigate tasks by time period

More about Notes

* Using Allout Mode::           Quickly navigating your notes
* <notes>::                     Note headlines
* <past-notes>::                Index of past notes
* Note Indices::                planner-notes-index.el

Publishing

* Publishing Planner pages::    planner-publish.el
* Publishing Calendars::        planner-calendar.el
* Authz Access Restriction::    planner-authz.el
* RSS Publication::             Sharing notes with planner-rss.el
* iCal Task Publication::       Sharing tasks with planner-ical.el
* RDF Publication::             planner-rdf.el

RDF Publication

* Publishing with planner-rdf::  
* planner-rdf Tags::            
* planner-rdf Usage Examples::  

Managing Your Information

* E-mail::                      Linking notes and tasks to messages
* Scheduling and Time::         Tracking appointments and where your time goes
* Finances::                    Display your account balances and more
* Contacts and Conversations::  BBDB and ERC
* Tracking Research and Resources::  The Web, bibliographies, and bookmarks
* Tracking Development::        

E-mail

* Unix mail::                   Unix mailboxes: planner-unix-mail.el
* Gnus::                        Gnus mail and news reader: planner-gnus.el
* VM::                          VM mail reader: planner-vm.el
* Wanderlust::                  Wanderlust mail reader: planner-wl.el
* MH-E::                        MH-E mail reader: planner-mhe.el
* Rmail::                       Rmail: planner-rmail.el

Scheduling and Time

* Diary::                       Using the Emacs diary: planner-diary.el
* Appointments::                Appointments in plan pages: planner-appt.el
* Timeclock::                   Time tracking: planner-timeclock.el
* schedule.el::                 Project completion: planner-schedule.el

Diary

* Planner-Diary Advanced Features::  

Usage

* Task-based Appointments::     
* Schedule-based Appointments::  
* Viewing Appointments::        
* Appointment Updating on Save::  
* Appointment and Calendar Integration::  
* Appointment Hooks::           

Finances

* Ledger::                      Personal finances: planner-ledger.el

Contacts and Conversations

* BBDB::                        Contacts: planner-bbdb.el
* Emacs Relay Chat::            Internet Relay Chat: planner-erc.el

Tracking Research and Resources

* W3m::                         Web browser: planner-w3m.el
* BibTeX::                      Bibliographies: planner-bibtex.el
* Bookmark::                    Bookmarks: planner-bookmark.el

Tracking Development

* Log Edit::                    Changelogs: planner-log-edit.el
* PSVN::                        svn changesets: planner-psvn.el
* XTLA::                        TLA changesets: planner-xtla.el
* Gnats::                       Gnats: The GNU bug reporting system

Advanced Configuration

* Customizing Your Day Pages::  Change your templates
* Variables to Customize::      Change various aspects of Planner behavior
* Ideas for Other Keybindings::  Add to and change the default keybindings

Reference Material

* Keeping Track of Time::       
* Other Interactive Functions::  
* Planner Keybindings::         Default keybindings for Planner
* Sample Configuration Files::  

Sample Configuration Files

* File Organization::           
* Bare-Bones Planning::         
* Bare-Bones Planning with Plan Pages::  
* Tasks on Plan Pages with Some Day Pages::  
* Hierarchical Tasks::          

@end detailmenu
@end menu

@node Preface, Introduction, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Preface

This document describes Planner, which was written by John Wiegley and
is now maintained by John Sullivan (@pxref{Acknowledgements}).

This document is a work in progress, and your contribution will be
greatly appreciated. Please e-mail comments and suggestions to the
mailing list (@pxref{Getting Help}). In the subject line of your
e-mail, include the word @samp{Planner}.

This documentation is available in eye-pleasing formats including PDF
and HTML at @url{http://wjsullivan.net/static/doc/planner/}.

Documentation author and maintainer: John Sullivan
@email{john@@wjsullivan.net}

@*
John Sullivan (johnsu01)@*
April 25, 2004

@node Introduction, Installation, Preface, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

Planner is an organizer and day planner for Emacs.  It helps you keep
track of your pending and completed tasks, daily schedule, dates to
remember, notes and inspirations. It is a powerful tool not only for
managing your time and productivity, but also for keeping within easy
keystroke reach all of the information you need to be productive. It can
even publish reports charting your work for your personal web page, your
conscience, or your soon-to-be-impressed boss.

In fact, because it uses as its building blocks simple plain-text files,
it is an incredibly modular and flexible tool capable of shaping and
handling your personal information in ways whose variety is limited only
by your imagination. Because of this, Planner has a very active and
generous community who regularly share their innovations with each
other. Many of these modules and extensions are included in the archive
that you will download. Once you get the basics down, you'll probably
want to explore some of them. But as you read this manual and work with
Planner, keep in mind that the basic core is actually very simple, and
it might be worth spending time with just that before delving into the
customizations.

Because they are plain text with very few requirements, the organizer
pages kept by Planner 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.

To get started with Planner, you first need to download it, and possibly
also the packages it depends on (@pxref{Installation}).

@node Installation, Overview, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installation
@cindex installation

Planner depends on Muse. Information for downloading and installing
Muse can be found at
@url{http://mwolson.org/static/doc/muse.html}.

Planner and Muse are intended to work with version 21 or later of Emacs
and XEmacs.

Make sure that you use the latest Muse release.  Development code might
prove unstable.

@menu
* Getting the Files::           
* Creating Your Planner::       
* Components::                  
* Advanced Installation::       
@end menu

@node Getting the Files, Creating Your Planner, Installation, Installation
@comment node-name,  next,  previous,  up
@section Getting the Files

Currently, there are three ways to obtain and install Planner. You can
install it from a source archive, git, or Debian package.

@menu
* Installing from a Source Archive::  
* Installing from git::         
* Installing from Debian::      
@end menu

@node Installing from a Source Archive, Installing from git, Getting the Files, Getting the Files
@comment node-name,  next,  previous,  up
@subsection Installing from a Source Archive
@cindex source code archive, installing from

You can install Planner from the source archive packaged and
distributed directly by the maintainer. This archive is provided in
both @file{.tar.gz} and @file{.zip} format.  If you don't know where to
extract these archives, create a @file{~/elisp} directory, and extract
them there.

@enumerate
@item
Download and unpack either
@url{http://mwolson.org/static/dist/planner-latest.tar.gz} or
@url{http://mwolson.org/static/dist/planner-latest.zip}.

@item
Likewise for
@url{http://mwolson.org/static/dist/muse-latest.tar.gz} or
@url{http://mwolson.org/static/dist/muse-latest.zip}.

@item
Likewise for
@url{http://mwolson.org/static/dist/remember-latest.tar.gz} or
@url{http://mwolson.org/static/dist/remember-latest.zip}.

@item Edit your @file{~/.emacs} (@file{_emacs} on Microsoft Windows).

Replace @file{/path/to} with wherever you extracted the files.

@example
;; Add the directories to your load path
(add-to-list 'load-path "/path/to/muse/lisp")
(add-to-list 'load-path "/path/to/planner")
(add-to-list 'load-path "/path/to/remember")

;; Load planner
(require 'planner)
@end example
@end enumerate

@subheading Updating Your Version

Download a new version and extract it over the old directory. Don't
forget to delete any byte-compiled files (@file{*.elc}) in the
directories (which can be accomplished by running ``make clean'') so
that the new code will be used.

@node Installing from git, Installing from Debian, Installing from a Source Archive, Getting the Files
@comment node-name,  next,  previous,  up
@subsection Installing from git

@cindex git version control system, using
The git version control system allows you to keep up-to-date with the
latest changes to the development version of Planner.  It also allows
you to contribute changes (via commits, if you are have developer access
to the repository, or via patches, otherwise).  If you would like to
contribute to Muse development, it is highly recommended that you use
git.

Debian users can install git with @kbd{apt-get install git-core}.

If you are new to git, you might find this tutorial helpful:
@uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.

Downloading Planner with git and staying up-to-date involves the
following steps.

@example
# Retrieve Muse
git clone git://repo.or.cz/muse-el.git muse

# Retrieve Planner
git clone git://repo.or.cz/planner-el.git planner

# Retrieve Remember
git clone git://repo.or.cz/remember-el.git remember

# If that didn't work (due to a restrictive firewall), then try the
# following instead:
#
# git clone http://repo.or.cz/r/muse-el.git muse
# git clone http://repo.or.cz/r/planner-el.git planner
# git clone http://repo.or.cz/r/remember-el.git remember
@end example

Then add the following lines to your @code{~/.emacs}:

@example
;; Add the directories to your load path
(add-to-list 'load-path "/path/to/muse/lisp")
(add-to-list 'load-path "/path/to/planner")
(add-to-list 'load-path "/path/to/remember")

;; Load planner
(require 'planner)
@end example

You can also browse Planner's git repository on the web at
@url{http://repo.or.cz/w/planner-el.git}.

@subheading Updating Your Version
@cindex git, updating with

To stay up-to-date using git, here are some commands that might be
useful.

To list upstream changes not in local copy:

Do this whenever you want to see whether new changes have been committed
to Planer.  If you wish, you may skip this step and proceed directly to
the ``update'' step.

@example
# Change to the source directory you are interested in. Example:
cd muse/

# Fetch new changes from the repository, but don't apply them yet
git fetch origin

# Display log messages for the new changes
git log HEAD..origin
@end example

``origin'' is git's name for the location where you originally got Muse
from.  You can change this location at any time by editing the
@file{.git/config} file in the directory where the Planner source was
placed.

To update to the latest version:

@example
cd muse; git pull
cd ../planner; git pull
cd ../remember; git pull
@end example

Don't forget to either rerun the @command{make} command or delete the
byte-compiled files (@file{*.elc}) in the directories, so that the new
code will be used.

@node Installing from Debian, , Installing from git, Getting the Files
@comment node-name,  next,  previous,  up
@subsection Installing from Debian
@cindex Debian package

Debian packages for Planner, Muse, and Remember are available in Debian
proper as the @code{planner-el}, @code{muse-el}, and @code{remember-el}
packages, respectively.

If you wish to try experimental packages, add the following lines to
your @file{/etc/apt/sources.list}

@example
deb http://mwolson.org/debian/ ./
@end example

Then, do the following steps as root:

@example
apt-get update
apt-get install muse-el
apt-get install planner-el
apt-get install remember-el
@end example

If you get some warning about the key not being trusted, you can either
ignore it or do the following.

@example
gpg --keyserver pgpkeys.mit.edu --recv-key f3a8d319
gpg -a --export f3a8d319 | sudo apt-key add -
@end example

@subheading Updating Your Version
@cindex Debian package, updating

If you installed Planner from Debian, do @kbd{apt-get update; apt-get
upgrade} to upgrade all packages that can be upgraded, or @kbd{apt-get
update; apt-get install planner-el} to upgrade just planner-el.

@node Creating Your Planner, Components, Getting the Files, Installation
@section Creating Your Planner

Now that you have installed the files for Planner and Muse, you need
to set some options to create your first planner.

Muse thinks in terms of projects. Each project consists of a group of
documents and certain information associated with these
documents. Planner is organized as a project within Muse. So, you need
to tell Muse a bit about it.

Add something like the following code to your @file{.emacs} file.

First, give your new Planner project a name. In this case, we use the
name, ``WikiPlanner''.

@example
(setq planner-project "WikiPlanner")
@end example

Next, add an entry for your project to Muse's master list of
projects. Don't forget to use your own name here in place of
``WikiPlanner'' if you have chosen something different.

@example
(setq muse-project-alist
      '(("WikiPlanner"
         ("~/Plans"           ;; where your Planner pages are located
          :default "TaskPool" ;; use value of `planner-default-page'
          :major-mode planner-mode
          :visit-link planner-visit-link)

         ;; This next part is for specifying where Planner pages
         ;; should be published and what Muse publishing style to
         ;; use.  In this example, we will use the XHTML publishing
         ;; style.

         (:base "planner-xhtml"
                ;; where files are published to
                ;; (the value of `planner-publishing-directory', if
                ;;  you have a configuration for an older version
                ;;  of Planner)
                :path "~/public_html/Plans"))))
@end example

This code should work fine as-is for you as long as the directories
you see exist, and as long as you have no other Muse projects besides
your planner.

The first directory (@file{~/Plans}) is the directory where the
source files for your planner will reside. This is the directory where
you will actually visit files and edit them.  These files must have a
``.muse'' extension.

The second directory (@file{~/public_html/Plans}) is the directory
where your planner files will be published by Muse as XHTML
(@pxref{Publishing}).

After you have added this code, make sure to either evaluate it or
restart Emacs.

@node Components, Advanced Installation, Creating Your Planner, Installation
@comment node-name,  next,  previous,  up
@section Components

Now that you have the archive, let's look at what's in it.

There should be three directories, named @file{planner}, @file{muse} and
@file{remember}.

In the @file{planner/} directory, you'll see many files with names like
@file{planner-gnus.el}. These are extra modules and extensions for
Planner, which you can use to tailor Planner to fit your desired
planning and information management habits.

In the @file{muse/lisp} directory, you'll see many files with names like
@file{muse-blosxom.el}. As in @file{planner/}, these are optional
modules and extensions.

A minimal working installation includes just @file{planner/planner.el}.

You need @file{planner.el} because it provides the core functions for
handling tasks, notes, and page navigation. You need @file{Emacs Muse}
because it provides the functions used to display your pages (both in an
emacs buffer and as HTML), and for connecting them to each other. More
specifically, it enables you to have hyperlinks and formatting in your
emacs buffers even though the actual files you are working with are
saved in plain text. These abilities are used in Planner 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 in different formats, including HTML.

In the @file{remember/} directory are files related to
RememberMode. RememberMode does not depend on Planner or Muse, but works
best with Planner installed. It is not required in order to use Planner,
but it is used by many Planner users to record notes and information to
their planner pages.

If you are curious, you can open each file in these directories and read
the comments at the top, to get an idea of what each extension is used
for. They are also all detailed later in this manual.

@node Advanced Installation,  , Components, Installation
@comment  node-name,  next,  previous,  up
@section Advanced Installation

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

@itemize
@cindex installing the info file
@cindex @file{planner-el.texi}, installing
@cindex @file{planner-el.info}, installing
@item You can make this document, the Planner info file, appear in
the index of info files you see when you type @command{M-x info} or
@kbd{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 @ref{Installing an Info File, ,
,texinfo, Texinfo}, using something like:

@example
* Planner: (path/to/planner/Planner). Organizer/day planner
for Emacs.
@end example

for the new entry in the info @file{dir} file.

@cindex byte compiling
@item You can byte-compile @file{planner.el}, @file{Muse},
@file{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 (1) change the directory for each project listed in
@file{scripts/planner-build.el}, (2) copy @file{Makefile.defs.default}
to @file{Makefile.defs} and edit it as needed, and (3) run
@command{make} from the command line. To read more detail about byte
compilation, see @ref{Byte Compilation, , ,elisp, Emacs Lisp Reference
Manual}.

@end itemize

@node Overview, Getting Started, Installation, Top
@comment node-name,  next,  previous,  up
@chapter Overview

Planner is a plain-text hyperlinked personal information manager
for Emacs that helps you keep track of tasks, notes, and other
information. People use Planner to support different ways of planning
one's day, from Franklin-Covey and David Allen's Getting Things Done
to home-brew hacks. Planner is even used to manage information not
normally handled by a personal information manager, like bugtracking,
time tracking, and team data. If you start by using Planner as a basic
TODO and notes manager, you might find other ways it can help you
improve your process.

You can use Planner to keep track of your tasks, schedule, notes,
and other information you want to store in hyperlinkable text files.
You can get the most benefit out of a personal information manager if
you use it everyday. Most people add @code{(plan)} to the end of their
@file{~/.emacs} so that Planner shows today's schedule and
unfinished tasks whenever Emacs starts. If you leave your Emacs
running for more than 24 hours, try to get into the habit of running
@code{plan} at least once a day.

Because your time is important, Planner tries to minimize
distractions, making it easier for you to jot down tasks and notes
without being distracted from your work. People often make tasks based
on the current buffer, so Planner tries to create hyperlinks to
whatever you're looking at so that you can jump back to it easily. The
@ref{Getting Started} tutorial will show you how to set that up for
both tasks and notes.

The customizability of Planner means you can make your personal
information manager truly personal. Planner strives to be as flexible
as possible, and we would love to adapt Planner to fit your needs.
Browse through our mailing list (@pxref{Getting Help}) to
find out how other people are using Planner, and post your feature
requests and bug reports there!

Planner is just a tool. It does not dictate a particular way of
planning, although it supports some ways better than it supports
others. If you want to take some time thinking about planning, read
the following reflections for inspiration and ideas. On the other
hand, if you want to hit the ground running, see @ref{Getting
Started}. If you already have a specific way of planning in mind,
check out @ref{Sample Configuration Files}.

@menu
* Planning based on the Franklin-Covey Approach::  
* Why Use Planner::             
@end menu

@node Planning based on the Franklin-Covey Approach, Why Use Planner, Overview, Overview
@comment  node-name,  next,  previous,  up
@section Planning Based on the Franklin-Covey Approach
@cindex philosophy of planning

(This is an edited and updated version of an essay originally by John
Wiegley. Read it if you want to get some insights into one way of
planning. You can skip this if you want to go straight to planning your
day.)

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 insecure
foundation.  If you follow your plan doggedly, applying some time to
it each day or week, it @emph{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
@url{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 installing Planner and Muse (@pxref{Installation}).

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 @kbd{C-x C-f}) within the directory you named in
your @code{muse-project-alist}. Make sure the file has a @file{.muse}
extension so that Emacs will automatically recognize it as a planner
file. Name the file after your plan, such as @file{BetterHealth.muse}.

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 @emph{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 @file{BetterHealth}.  Start typing.
Type anything related to your idea: what you think about it, your
ideas on it, @emph{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. You might
find it convenient to name these pieces using MixedCase words. Try
adding these lines to your @file{.emacs} or @file{_emacs} file.

@example
(require 'muse-wiki)
(setq muse-wiki-allow-nonexistent-wikiword t)
@end example

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 @kbd{C-c C-t}. This
will ask for a brief description of the task, and when you plan to do
it. If you hit @key{RETURN} at the question @samp{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 @code{mark-diary-entries-in-calendar} to @samp{t} in your
@file{.emacs} (or @file{_emacs}) file. This way, you can see which
days your appointments fall on. (Read about the Emacs Calendar and
Diary in @ref{Calendar/Diary, , , Emacs, GNU Emacs Manual}.)

@example
(setq mark-diary-entries-in-calendar t)
@end example

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 @kbd{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
@kbd{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 @kbd{C-c C-n} (from a
Wiki or planning page).  I heartily recommend binding @kbd{C-c n}, to
jump you to this page from anywhere:

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

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 @kbd{C-c C-i}
(assuming you have @file{timeclock.el} on your load-path), it will log
the time you spend working on your sub-plan (@pxref{Time Intervals, , ,
Emacs, GNU Emacs Manual}). This is helpful for viewing your progress.
Type @kbd{C-c C-o} to clock out.

@kbd{C-M-p} and @kbd{C-M-n} will move a task up and down in priority.
Priority is represented by a letter A through C.  '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.

@defun plan force-days
Start your planning for the day, beginning with the last day's tasks.

If @code{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 @var{force} is non-nil, examine all past daily
pages for unfinished tasks.

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

If @var{force-days} is a positive integer, scan that number of days.
If @var{force-days} is @samp{t}, scan all days.

@end defun

@node Why Use Planner,  , Planning based on the Franklin-Covey Approach, Overview
@comment  node-name,  next,  previous,  up
@section Why Use Planner?
@cindex Planner, why use

You can skip this essay if you just want to get started, or read it
for some insights into why the previous maintainer is crazy about it.

Why I Use Planner, by Sacha Chua

I thought about why I liked Planner. Planner as a TODO manager
isn't particularly special. Although I can assign tasks to categories
and 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, Planner is also not particularly distinguished.
Sure, it can display my @file{~/diary}, but for that matter so can
@kbd{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, Planner 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. (I've defined a
few shortcut keys to deal with this.) 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.

Planner'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. (Note: You'll need remember.el for
this.)

I guess that's why I like Planner. Unlike other organizers which
don't know anything about the applications I use, Planner 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.

(That said, it's perfectly okay to use Planner even if you don't live
in Emacs.)

The processing that happens in the background 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. (Again, this is purely optional. Many
people don't publish their planner pages. Other people use really
fine-grained access control.)

I think the greatest feature of Planner, though, is its user
community. Because Planner can be easily modified, we can experiment
with a lot of new ideas quickly, and we can tailor Planner to fit our
needs. I love checking my @samp{planner-el-discuss} mail and finding
out how people have tweaked Planner or would like to tweak Planner,
and I've learned a lot by exchanging reflections on organizing one's
life.

I really wasn't an organization freak before I started using Planner.
I often forgot to do my homework or answer important mail. I still
procrastinate now, but at least it's all being kept track of
somewhere! I also really like how Planner lets me to gradually improve
how I'm doing things, and I feel I've come a long way.

Please try it out! We'd love to hear how Planner can become
@emph{your} personal information manager.

@node Getting Started, More about Planner, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Started

At the end of this tutorial, you will be able to use Planner and
related modules to keep track of your tasks, schedules and notes, all
within the convenience of Emacs.

There are two kinds of pages in a Planner wiki. Day pages show tasks,
schedule, and notes for the day, while plan pages organize related tasks
and notes into a single page.

If you have not yet added planner to your @file{~/.emacs}, add the
following lines:

@example
(add-to-list 'load-path "/path/to/muse/lisp")
(add-to-list 'load-path "/path/to/planner")
(add-to-list 'load-path "/path/to/remember")
(require 'planner)
@end example

This will bring up the most recent day page with unfinished tasks or
create a new day page if necessary. By default, planner pages are
stored in @samp{~/Plans} (@code{planner-directory}).

@menu
* Tasks::                       
* Schedule::                    
* Notes::                       
* Hyperlinks::                  
* Example Page::                
* Review::                      
@end menu

@node Tasks, Schedule, Getting Started, Getting Started
@section Tasks

Let us start by creating a task labelled

@example
Join http://mail.gna.org/listinfo/planner-el-discuss/
@end example

From anywhere (even this info buffer!), call @kbd{M-x
planner-create-task-from-buffer} to create a new task. Fill in the
description and choose a date by:

@itemize
@item typing 1 - 31 to put the task on that day of the month,
@item accepting the default (today) by pressing RET,
@item selecting the date with mouse-1,
@item
typing +n (where in is an integer) to schedule the task in n days time,
or
@item typing nil to make an undated task.
@end itemize

For now, accept the default (@samp{today}) by pressing @key{RET}.

You will then be prompted for a plan page. Plan pages gather related
tasks and notes, giving you an overview of what you've done so far.
You can accept the default TaskPool, create your own plan page, or
specify nil to make a task that is not associated with a plan page.
For now, accept the default (@samp{TaskPool}) by pressing RET.

You have created your first task. View today's page with
@kbd{M-x planner-goto-today}. You will see a line of the form

@example
#B  _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
@end example

If you created the task from this page, then there will be an additional
annotation:

@example
#B  _ Join http://mail.gna.org/listinfo/planner-el-discuss/ : Tasks (TaskPool)
@end example

The URL, @samp{TaskPool} and @samp{Getting Started} are
hyperlinks. You can use TAB and S-TAB to navigate between them and RET
to follow the link.

Create more tasks using @kbd{M-x planner-create-task-from-buffer}.
This is bound to @kbd{C-c C-t} in @code{planner-mode} pages
for your convenience. For example, create the following tasks:

@itemize
@item
@samp{Describe my current way of working and how I would like to work},
for three days from now (@samp{+3}),
@item
@samp{Learn how to schedule a task}, an undated task (@kbd{nil}) on the
TaskPool page,
@item
@samp{Browse through the Planner info manual} for today (@kbd{.} or
accept the defaults), and
@item
@samp{Add (plan) to the end of my [[~/.emacs]]} for today, but without a
plan page (specify @kbd{nil} at the plan page prompt)
@end itemize

Tip: I bind planner-create-task-from-buffer to "F9 t" so that I can
easily call it from anywhere. You can do that with this elisp fragment:
@code{(global-set-key (kbd "<f9> t") 'planner-create-task-from-buffer)}

Next, visit the TaskPool by:

@itemize
@item
@key{TAB}-bing or using the cursor and typing @key{RET} to follow the
link,
@item @kbd{C-x C-f TaskPool RET} to use @code{find-file}, or
@item @kbd{C-c C-f TaskPool RET} to use @code{muse-project-find-file}
@end itemize

You can see an overview of the tasks as scheduled on different days.
Unlike many personal information managers that store all of your data
in one file and then perform magic in order to present different
views, Planner uses plain text files. The data is duplicated and kept
updated by functions. This makes it simpler and easier to modify,
because what you see is (almost) what you get. On the other hand,
you'll need to get used to either editing both files, or using the
built-in functions for editing and updating files. If you prefer not
to work with linked tasks, you can configure Planner to use only plan
pages or use only day pages.

The TaskPool page should list the tasks you created earlier. Go to the
one named Learn how to schedule a task . Type @kbd{C-c C-c}
(@code{planner-copy-or-move-task}) to schedule the task. Type RET to
accept the default (today). Go to the day page by following the link
or calling @kbd{M-x planner-goto} (@kbd{C-c C-j C-d} or the menu bar);
you will see the newly-created task there. You can also use @kbd{C-c
C-c} (@kbd{planner-copy-or-move-task}) to reschedule a task to an
earlier or later date.

Well, that task is done. To mark the task as completed, type @kbd{C-c
C-x} (@code{planner-task-done}). You can also edit the status manually
(change _ to X) as long as you remember to call @kbd{M-x
planner-update-task} to update the link page as well. Updating relies on
the task description being the same, so do not edit this manually.

Quick summary of commands:

@itemize
@item
Go to today's page: @kbd{M-x plan} to carry unfinished tasks forward, or
@kbd{M-x planner-goto-today} to just go to today's page.
@item
Create a task: @kbd{C-c C-t} (@code{planner-create-task-from-buffer}),
or type a task manually (call M-x planner-update-task if the task is
linked)
@item
Mark a task as done: @kbd{C-c C-x} (@code{planner-task-done}), or edit
the task and call @kbd{M-x planner-update-task}
@item Edit a task description: @kbd{M-x planner-edit-task-description}
@item Reschedule a task: @kbd{C-c C-c} (@code{planner-copy-or-move-task})
@item
Reschedule many tasks: Mark a region and use @kbd{M-x
planner-copy-or-move-region}
@item
Change the plan of a task: @kbd{M-x planner-replan-task}, or do
@kbd{C-c C-c} (@code{planner-copy-or-move-task}) and type in a
plan page rather than a date
@item Delete a task: @kbd{M-x planner-delete-task}
@item
Reorder tasks: @key{M-p} (@code{planner-raise-task}) and @key{M-n}
(@code{planner-lower-task}), or normal editing commands like kill and
yank
@item Change task priorities (@samp{#A} > @samp{#B} > @samp{#C}):
      @key{C-M-p} (@code{planner-raise-task-priority}) and
      @key{C-M-n} (@code{planner-lower-task-priority}),
      or edit the task and call @kbd{M-x planner-update-task}.
@end itemize

You can save your tasks with @kbd{C-x C-s} the same way you save any
other file, or Emacs will prompt you to save it when you exit.

@node Schedule, Notes, Tasks, Getting Started
@comment  node-name,  next,  previous,  up
@section Schedule

This is free-form. You can put anything you want into this, or remove
it from @code{planner-day-page-template} entirely. Some people use it
to keep track of their plans for the day with tables like this:

@example
hh:mm | hh:mm | activity
hh:mm | hh:mm | activity
hh:mm | hh:mm | activity
@end example

Remember, Planner files are just plain text. You can add new sections
or remove old ones, or use the suggested sections for entirely
different activities.

@node Notes, Hyperlinks, Schedule, Getting Started
@comment  node-name,  next,  previous,  up
@section Notes
@cindex @file{remember.el}
@cindex @file{remember-planner.el}
@cindex notes

By default, your Planner pages will have a Notes section. You can put
anything you want in this section, or remove it from your
@code{planner-day-page-template} entirely.

You may be interested in @file{remember-planner.el}, part of the
Remember package (see @inforef{Top, remember-el, remember-el}). You
can download Remember at @uref{http://gna.org/projects/remember-el/}).

@code{remember-planner.el} makes it easy to create notes from anywhere
in Emacs, and it uses the same context-sensing code that Planner uses.
Notes added by @code{remember-planner.el} look like this:

@example
.#1 Headline 00:00
Body

[[context hyperlink]]
@end example

and are outlined at the H2 level in published HTML.

You can easily create context-aware notes if you include the following
in your @file{~/.emacs}:

@example
(require 'remember-planner)
(setq remember-handler-functions '(remember-planner-append))
(setq remember-annotation-functions planner-annotation-functions)
@end example

Then @kbd{M-x remember} will open a dedicated buffer for you to write
your note. If Planner recognizes your current buffer as one with
context then it will include a hyperlink at the bottom of the note.
The first line of the note is used as a title, so make it short and
meaningful. The rest of the text will be used as the body. Try it now
by creating a note, perhaps about things you'd like to remember from
this tutorial.

Typing @kbd{C-c C-c} after composing will prompt for a plan page to
put the note on, with auto-completion. If you don't enter a page, the
note will just be saved on today's page. If you do specify a plan
page, the note will go on both today's page and on the specified page.
Let's try specifying @samp{TaskPool} for the note.

If you look at today's page, you'll find a timestamped note that links
to @samp{TaskPool}. Likewise, @samp{TaskPool} contains a note that
links to today's page. To change the plan page of a note, use
@kbd{planner-replan-note}.

If you decide to edit the note on one of these pages after it has been
saved, be aware that your changes will not be automatically reflected
on the linked page. To update the linked page after editing a note,
use @kbd{M-x planner-update-note}.

@node Hyperlinks, Example Page, Notes, Getting Started
@section Hyperlinks
@cindex hyperlinks

Planner automatically creates context-sensitive hyperlinks for your
tasks and notes when you use @code{planner-create-task-from-buffer}
and @code{remember}.

Blue links indicate URLs and Planner pages that already exist. Red links
indicate Planner pages that have not yet been created.

Middle-click or type @key{RET} on any link to view the link in the
current window. Shift-middle-click or type @key{S-RET} to view the
link in another window. @key{TAB} goes to the next link, while
@key{S-TAB} goes to the previous one.

You can pick up hyperlinks using the @code{planner-annotation-as-kill}
function.

@defun planner-annotation-as-kill
Create a context-sensitive hyperlink for the current buffer and copy
it to the kill ring. When called with a prefix argument, prompt for
the link display name.
@end defun

You can then paste it into any Planner buffer by using @kbd{M-x yank}
or the keyboard shortcut.

Alternatively, you can create hyperlinks by typing them directly, using
the syntax defined by Muse. Anything inside double square brackets will
be treated as a link. For example, if you type @samp{[[GroceryList]]} in
a Planner buffer, you will end up with a link to a page called
@samp{GroceryList}. @inforef{Implicit Links, Bare URLs WikiNames and
InterWiki links, muse}, for more information about Muse syntax.

Hyperlinks are a powerful feature of Planner. You can use them to
hyperlink to mail, news, Web pages, and even IRC connections. See the
section on @ref{Managing Your Information} to find out how to enable
support for various parts of Emacs. Want to add a new hyperlink
scheme? Check out the source code for examples or ask on the mailing
list for help.

@node Example Page, Review, Hyperlinks, Getting Started
@comment  node-name,  next,  previous,  up
@section Example Page
@cindex example page
@cindex planning page, example

An example planner file is given below. You'll notice that Planner
does not have a well-defined user interface. Rather, it's free-form
and open, allowing you to adapt it to your preferences.

@example
----------------------------------------------------------------------
* Tasks

#B  _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
#B  _ Browse through the Planner info manual (TaskPool)
#B  _ Add (plan) to the end of my ~/.emacs
#B  X Learn how to schedule a task (TaskPool)

* Schedule

18:00 | 19:00 | Learn how to use Planner

* Notes

Notes are free-form. You can put anything you want into this.

.#1 This is note number one

Notes on note number one!

.#2 This weird ".#2" syntax is used for allout.el enumerated lists

It makes using allout-mode very handy.

@end example

@node Review,  , Example Page, Getting Started
@comment  node-name,  next,  previous,  up
@section Review

@itemize

@item @emph{Ideas for using planner more effectively:}

@itemize
@item
Add @code{(plan)} to the end of your @file{~/.emacs} so that you are
reminded about your tasks every day.

@item
Bind useful functions to shortcut keys and get used to creating tasks
and notes from anywhere.

@item
Think about how you plan your day and look for ways to improve it. Ask
the mailing list (@pxref{Getting Help}) for tips.

@item
Browse the rest of this manual, the source code, and other resources on
the Net for tidbits you can use.

@item Have fun!
@end itemize

@item @emph{Useful functions outside planner buffers:}

@itemize
@item @code{planner-create-task-from-buffer}
@item @code{remember}
@item @code{planner-goto-today}
@item @code{planner-goto}
@item @code{plan}
@end itemize

@item @emph{Useful functions inside planner buffers:}

@itemize
@item @kbd{C-c C-t} (@code{planner-create-task-from-buffer})
@item @kbd{C-c C-x} (@code{planner-task-done})
@item @kbd{M-x planner-edit-task-description}

@item
@kbd{C-c C-c} (@code{planner-copy-or-move-task}), @kbd{M-x
planner-copy-or-move-region}

@item @kbd{M-x planner-replan-task}
@item @kbd{M-x planner-delete-task}

@item
@key{M-p} (@code{planner-raise-task}) and @key{M-n}
(@code{planner-lower-task})

@item @key{C-M-p} (@code{planner-raise-task-priority}) and
      @key{C-M-n} (@code{planner-lower-task-priority}),
@item @code{planner-replan-note}
@item @code{planner-update-note}
@end itemize

@end itemize

That's all you need to know in order to use Planner as a basic TODO and
notes manager, but there's a whole lot more. Read through this manual
and our mailing list archives (@pxref{Getting Help}) for lots of
wonderful ideas about planning in Emacs!

@node More about Planner, Managing Your Information, Getting Started, Top
@comment  node-name,  next,  previous,  up
@chapter More about Planner

@menu
* Navigation::                  
* More about Tasks::            
* More about Notes::            
* Making Files Pretty::         
* Annotations::                 
* Interactive Lisp::            planner-lisp.el
* Publishing::                  planner-publish.el
* Experimental Functions::      planner-experimental.el
@end menu

@node Navigation, More about Tasks, More about Planner, More about Planner
@comment  node-name,  next,  previous,  up
@section Starting with Day Pages

@command{planner-goto-today} opens today's page.  Day pages are named
@samp{YYYY.MM.DD} and contain your notes for the day.

You should see a file that looks like this:

@example
* Tasks


* Schedule

* Notes
@end example

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

Use the following commands to navigate through day pages:

@defun plan
Start planning the day.  If @code{planner-carry-tasks-forward} is
non-nil, copy the most recent unfinished tasks to today's page, else
open the most recent page.
@end defun

@defun planner-goto (@kbd{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

@itemize
@item @kbd{+1} is one day from now, or @samp{2004.05.06}
@item @kbd{-1} is one day before now, or @samp{2004.05.04}
@item @kbd{12} is equivalent to @samp{2004.05.12}
@item @kbd{8.12} is equivalent to @samp{2004.08.12}
@item @kbd{2005.08.12} is a full date specification
@end itemize

In the calendar buffer, you can also left-click or press @key{RET} on
a date to select it.
@end defun

@defun planner-goto-today (@kbd{C-c C-j C-j})
Display today's page. Create the page if it does not yet exist.
@end defun

@defun planner-goto-tomorrow (@kbd{C-c C-j C-t})
Goto the planner page days @var{after} the currently displayed date.
If @var{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.
@end defun

@defun planner-goto-yesterday (@kbd{C-c C-j C-y})
Goto the planner page @var{days} before the currently displayed date.
If @var{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.
@end defun

@defun planner-goto-most-recent
Go to the most recent day with planning info.
@end defun

@defun 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.
@end defun

@defun 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.
@end defun

@defun planner-goto-plan-page page
Opens @var{page} in the the @code{planner-project} Wiki.  Use
@code{planner-goto} if you want fancy calendar completion.
@end defun

@defun planner-show date
Show the plan page for @var{date} in another window, but don't select
it.  If no page for @var{date} exists, return nil.
@end defun


@node More about Tasks, More about Notes, Navigation, More about Planner
@comment  node-name,  next,  previous,  up
@section More about Tasks
@cindex tasks, more about

This section is divided into three parts. In the first part, you can
read about all the options, strategies and commands to help you
efficiently add new tasks to your planner. In the second part, we'll go
over all of the aspects of Planner that relate to organizing, editing,
rescheduling and viewing the tasks you've already created. Finally,
we'll cover some ways to step back and look at various reports and
overviews that can be generated from your planner pages.

You may also be interested in tracking time spent on tasks with
@ref{Timeclock} and estimating project completion time with
@ref{Schedule} (also see @pxref{schedule.el}).

@menu
* Creating New Tasks::          
* Organizing Your Tasks::       
* Task Reports and Overviews::  
@end menu

@node Creating New Tasks, Organizing Your Tasks, More about Tasks, More about Tasks
@comment  node-name,  next,  previous,  up
@subsection Creating New Tasks
@cindex tasks, creating

Planner makes it very easy to quickly add something to your list of
tasks. Once you get used to the basics of
@command{planner-create-task-from-buffer}, you might want to take a
closer look at some things in Planner that can help you create new tasks
in a way that fits with your system.

@menu
* Creating a Task::             
* Task Priorities::             
* Task IDs::                    planner-id.el
* Cyclic Tasks::                planner-cyclic.el
* Task Detail::                 
* Deadlines::                   planner-deadline.el
@end menu

@node Creating a Task, Task Priorities, Creating New Tasks, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Creating a Task
@cindex tasks, creating

You can create a task from any buffer in Emacs by invoking
@command{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 Planner
day page, Planner will associate the task with a hyperlink to that
buffer. Try it now by creating a task from this Info buffer.

@enumerate
@item @kbd{M-x planner-create-task-from-buffer}
@item
When prompted for the task name, enter @kbd{Learn how to change a task's
status} and press @key{RET}.

@item
When prompted for the date, press @key{RET} to schedule the task for
today.

@item
When prompted for the project page, press @key{RET} to accept the
default page of @samp{TaskPool}. This is a page for tasks not connected
to a larger plan.

@end enumerate

Planner 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 @key{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 @samp{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 @samp{06.16}. If you would
like to schedule something for next year, then enter the full date,
like @samp{06.16.2005}. If you do not want this task to appear on a
day page at all, you can enter @samp{nil}.

The second piece of information Planner 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 @samp{nil}. But instead, you might enter
@samp{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 Planner 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.

Planner 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 Planner 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 @kbd{SPC} or
@kbd{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, Planner gets out of your way, and you can go on
about your business. Later on, when you decide to actually work on
that ``Memorize Planner 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 Planner info file!

By default, @command{M-x planner-create-task-from-buffer} creates
medium-priority tasks, marked with the letter @samp{B}.  But you can
specify a particular priority or change the default (@pxref{Task
Priorities}).

You don't have to use @command{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 Planner expects. You
can even still create hyperlinks by using Muse formatting as you
manually type the new task (@pxref{Hyperlinks}). Keep in mind also that
tasks do not have to be linked to any other page.

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

@defun planner-create-task-from-buffer title date plan-page
Create a new task named @var{title} on @var{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 @code{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
@code{planner-add-task-at-end-flag}.
@end defun

@defun planner-create-task title date annotation plan-page
Create a new task named @var{title} based on the current Wiki page.
If @var{date} is non-nil, makes a daily entry on @var{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 (@pxref{Time Intervals, , ,
Emacs, GNU Emacs Manual}). If @var{annotation} is non-nil, it will be
used for the page annotation. If @var{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 @code{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
@code{planner-add-task-at-end-flag}.
@end defun

@node Task Priorities, Task IDs, Creating a Task, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection 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.

@itemize
@item @code{planner-create-high-priority-task-from-buffer}
creates a task with priority @samp{A}.

@item @code{planner-create-medium-priority-task-from-buffer}
creates a task with priority @samp{B}.

@item @code{planner-create-low-priority-task-from-buffer}
creates a task with priority @samp{C}.
@end itemize

Or, you can change the default priority of
@command{planner-create-task-from-buffer} by customizing
@var{planner-default-task-priority}.

You can actually use just one general priority, but using more than
one color-codes your tasks and gives you a better overview of your
day.


@node Task IDs, Cyclic Tasks, Task Priorities, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Task IDs
@cindex @file{planner-id.el}, using
@cindex tasks, IDs

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

@example
(require 'planner-id)
@end example

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

@subheading Options

@defopt planner-id-add-task-id-flag
Non-nil means automatically add global task IDs to newly-created
tasks. If nil, use @command{planner-id-add-task-id} to add IDs to
existing tasks, or @command{planner-id-add-task-id-to-all} to add to
all tasks on the current page.
@end defopt

@defopt planner-id-update-automatically
Non-nil means automatically update linked tasks whenever a page is
saved. If nil, use @command{planner-update-task} to update the linked
task. By default, linked tasks are automatically updated.
@end defopt

@defopt planner-id-tracking-file
File that contains ID tracking data. This file is automatically
overwritten.
@end defopt

@subheading Functions

The following interactive functions are defined in @file{planner-id.el}:

@defun planner-id-jump-to-linked-task &optional info
Display the linked task page. If @var{info} is specified, follow that
task instead.
@end defun

@defun 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.
@end defun

@defun 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 @code{write-file-functions}. If
@var{force} is non-nil, completed and cancelled tasks are also
updated.
@end defun

@defun planner-id-add-task-id-to-all
Add a task ID for all the tasks on the page. Update the linked page,
if any.
@end defun

@defun planner-id-search-id id
Search for all occurrences of @var{id}.
@end defun

@defun planner-id-follow-id-at-point
Display a list of all pages containing the ID at point.
@end defun

@defun planner-id-follow-id-at-mouse event
Display a list of all pages containing the ID at mouse. @var{event} is
the mouse event.
@end defun

@node Cyclic Tasks, Task Detail, Task IDs, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Cyclic Tasks
@cindex @file{planner-cyclic.el}, using
@cindex tasks, cyclic
@cindex cyclic tasks
@cindex recurring tasks

If there are tasks that you have to do regularly, you can have Planner
schedule those tasks automatically.

Make sure that @file{planner-cyclic.el} is in your load path and add
this to your @file{.emacs} (or @file{_emacs}):

@example
(require 'planner-cyclic)
@end example

Create a diary file named @file{~/.diary.cyclic-tasks}
(or the value of @code{planner-cyclic-diary-file}). Here is an example:

@example
Tuesday #B0 _ Study Japanese
Friday #B0 _ Study Japanese (JapaneseStudies)
@end example

The first will be a plain task, the second will be linked.  The first
line will automatically create its task every Tuesday, while the
second will create it every Friday.

You can schedule tasks in a variety of ways. This module uses the same
syntax for specifying when tasks will be scheduled as the Emacs diary
uses for appointments and events. See @ref{Date Formats, the GNU Emacs
Manual, Date Formats,emacs, the GNU Emacs Manual}, and @ref{Sexp Diary
Entries, the GNU Emacs Lisp Reference Manual, Sexp Diary
Entries,elisp, the GNU Emacs Lisp Reference Manual}, for a full
description of the possibilities.

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

@example
(setq planner-cyclic-diary-nag nil)
@end example

@subheading Functions

@file{planner-cyclic-diary} includes the following interactive
functions:

@defun planner-cyclic-create-tasks-maybe
Maybe create cyclic tasks. This will only create tasks for future
dates or today.
@end defun

@node Task Detail, Deadlines, Cyclic Tasks, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Task Detail
@cindex tasks

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.
@cindex tasks, sub-
@cindex tasks, meta-
@cindex meta-tasks
@cindex sub-tasks

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

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

@samp{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 @samp{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:

@example
#A1  _ First specific thing to do
@end example

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 @samp{#A1  _ Do things in
RevelleLog @{@{Tasks:101@}@} (RevelleLog)}.

As you can see, the ability to manually enter tasks is one of
Planner'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, Planner will continue to
recognize them as tasks.

Another way to have a task not be connected to a particular date is to
do @kbd{C-c C-c} (@code{planner-copy-or-move-task}) and specify
@samp{nil} when asked for the date.

If you would like to see a list of all of your unfinished scheduled
tasks, do @kbd{M-x planner-list-unfinished-tasks}.  It is only intended
to give you an overview.  Any editing you want to do, like marking tasks
complete or editing their description, still needs to be done on one of
the tasks' ``real'' planner pages.

@node Deadlines,  , Task Detail, Creating New Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Deadlines
@cindex tasks, deadlines for
@cindex deadlines, task
@cindex @file{planner-deadline.el}, using

You can use @file{planner-deadline.el} to automatically recalculate
days to a deadline by adding @code{(require 'planner-deadline)} to
your @file{~/.emacs}. With the default setup, make your tasks of the
form

@example
#A0 _ Some task @{@{Deadline: 2004.09.12@}@}
@end example

(Note: There must be at least one space after the colon.)

After you run @code{planner-deadline-update} to update task descriptions,
the task will be of the form

@example
#A0 _ Some task @{@{Deadline: 2004.09.12 - 2 days@}@}
@end example

@subheading Options

@defopt planner-deadline-regexp
Regular expression for deadline data.
The special deadline string should be regexp group 1. The
date (YYYY.MM.DD) should be regexp group 2.
@end defopt

@subheading Functions

@defun planner-deadline-update
Replace the text for all tasks with deadlines. Deadlines are of the
form @samp{@{@{Deadline: YYYY.MM.DD@}@}} by default.
@end defun

@defun planner-deadline-change &optional date
Change the deadline of current task to @var{date}. If @var{date} is nil,
remove deadline.
@end defun

@node Organizing Your Tasks, Task Reports and Overviews, Creating New Tasks, More about Tasks
@comment  node-name,  next,  previous,  up
@subsection Organizing Your Tasks
@cindex tasks, organizing
@cindex tasks, old

Okay, now that you've gotten the hang of creating tasks, you're probably
facing a really long list of things to do. How can you organize them so
that they don't overwhelm you? Planner gives you a number of strategies
for dealing with large numbers of tasks.

@enumerate
@item Arrange your tasks in the rough order you're going to do them.
@item Use #A, #B and #C task priorities to differentiate between
      high-priority, normal and low-priority tasks.
@item Schedule your tasks onto different days.
@item Group your tasks into plan pages.
@item Don't schedule all your tasks.
@end enumerate

@enumerate

@item @emph{Task order}

To remind yourself to do tasks in a certain order, simply edit the
lines so that they're in the order you want. You can use normal
editing commands like kill, yank and transpose-line to reorder the
tasks, or use @key{M-p} (@code{planner-raise-task}) and @key{M-n}
(@code{planner-lower-task}) to rearrange the tasks.

@item @emph{Task priorities}

By default, tasks are created with medium priority (@samp{#B}). You
can make a task high-priority (@samp{#A}) or low-priority (@samp{#C})
by manually editing the task and calling M-x planner-update-task to
update the linked page. Alternatively, you can use @key{C-M-p}
(@code{planner-raise-task-priority}) and @key{C-M-n}
(@code{planner-lower-task-priority}) to modify the task and update the
linked page.

You can edit the priority of a task using @kbd{M-x
planner-edit-task-priority}, or manually edit it and call @kbd{M-x
planner-update-task} to update tasks on the linked page.

@item @emph{Schedule your tasks on different days}

You don't have to do everything today. Is this a task you would rather
do tomorrow? Schedule it for then instead. You can specify @samp{+n}
or @samp{-n} whenever you are asked for a date, where @var{n} is the
number of days before or after the current file's date or today.
Don't over-procrastinate things, though!

@item @emph{Plan pages}

Plan pages let you group related tasks and notes together for easy
reference. For example, you could have a plan page for each major
project or goal in your life, like @samp{GoodHealth} or
@samp{FurtherStudies}.

Although plan pages start by grouping everything under a @samp{*
Tasks} header, you can organize your plan pages in different ways. For
example, you can separate groups of tasks with blank lines, and
Planner will sort tasks within each group.

@item @emph{Tasks without dates}

Plan pages also allow you to have undated tasks or tasks with no
particular deadlines. This keeps your daily task list small and
manageable while making it easier for you to find things to do if you
have free time. Make sure you check your plan pages regularly so that
you don't completely forget about them.

For automated scheduling of the next task on a plan page after you
complete a task, see the section in
@uref{http://sacha.free.net.ph/notebook/emacs/planner-config.el} named
``Schedule next undated task from same project''.

@end enumerate


@menu
* Multiple Projects::           
* Viewing Tasks::               
* Modifying Tasks::             
* Carrying Over Unfinished Tasks::  
* Task Numbering::              
* Task Ranks::                  planner-rank.el
* Grouping Tasks::              planner-trunk.el
@end menu

@node Multiple Projects, Viewing Tasks, Organizing Your Tasks, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Associating Tasks with Multiple Projects
@cindex multiple projects
@cindex @file{planner-multi.el}, using

You can use @file{planner-multi.el} to associate a task with more than
one project. That way, you can easily keep GTD-style context lists as
well as project-related lists.

To use multiple projects, add the following to your @samp{~/.emacs}:

@example
(require 'planner-multi)
@end example

Under GNU Emacs, you can specify multiple projects by separating them
with a single space. For example, you can specify @kbd{planner doc}
when creating a task to associate the task with those two projects.

Under XEmacs, you can specify multiple projects by typing @kbd{RET}
after each entry and terminating the list with another @kbd{RET}. For
example, to specify @kbd{planner} and @kbd{doc}, you would type
@kbd{planner RET doc RET RET} at the prompt.

If you want to see an overview of all of your tasks as well as
project- or context-specific lists, you can set
@code{planner-multi-copy-tasks-to-page} to your overview page(s). For
example, set it to @samp{TaskPool} to be able to see an overview of
all of your unfinished tasks. You can also set this to multiple pages
such as @samp{[[TasksByProject][p]] [[TasksByContext][c]]} and use
@file{planner-trunk.el} to sort and organize tasks for easy reference.
(@pxref{Grouping Tasks})

@subheading Options

@defopt planner-multi-copy-tasks-to-page
Automatically copy newly-created tasks to the specified page.
@end defopt

By default, tasks are removed from
@code{planner-multi-copy-tasks-to-page} when you call
@code{planner-task-done} or @code{planner-task-cancelled}. If you
prefer to keep a copy of the task, remove
@code{planner-multi-remove-task-from-pool} from
@code{planner-mark-task-hook}.

If you want to use a different separator instead of spaces, customize
the @code{planner-multi-separator} variable.

@defopt planner-multi-separator
String that separates multiple page references.

For best results, this should be something recognized by
@code{muse-link-at-point} so that links are highlighted
separately.
@end defopt

@node Viewing Tasks, Modifying Tasks, Multiple Projects, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Viewing tasks
@cindex tasks, viewing

Review the tasks scheduled for today by typing @kbd{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

@example
#A _ Learn how to change a task's status from Tasks (TaskPool)
@end example

If you have @code{planner-use-task-numbers} set to non-nil, you will see
something like the following instead.

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

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

@itemize
@item @samp{A} - Priority.  A (high)
@item
@samp{0} - Priority number.  It is calculated whenever you save the file
or call @command{planner-renumber-tasks}, provided that
@code{planner-use-task-numbers} is non-nil.  Tasks are numbered in
ascending order according to priorities.
@item @samp{_} - Status.  _ (unfinished)
@end itemize

If you click on @samp{Tasks} or press @key{RET} while your cursor is
in the link, Emacs will display the previous info page.

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

@subheading Functions

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

@defun planner-list-tasks-with-status status &optional pages
Display all tasks that match the STATUS regular expression on all day
pages.  The PAGES argument limits the pages to be checked in this
manner:

@itemize
@item @code{t}: check all pages
@item regexp: search all pages whose filenames match the regexp
@item list of page names: limit to those pages
@item alist of page/filenames: limit to those pages
@end itemize

Called interactively, this function will search day pages by
default. You can specify the start and end dates or leave them as
nil to search all days. Calling this function with an interactive
prefix will prompt for a regular expression to limit pages.
Specify @samp{.} or leave this blank to include all pages.

This function could take a long time.
@end defun

@defun planner-list-unfinished-tasks &optional pages
Display all unfinished tasks. @var{pages} follows
planner-list-tasks-with-status.
@end defun

@defun planner-jump-to-linked-task task-info
Display the task page linked to by the current task or
@var{task-info}.
@end defun

@node Modifying Tasks, Carrying Over Unfinished Tasks, Viewing Tasks, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Modifying Tasks
@cindex tasks, modifying
@cindex tasks, editing

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

Change a task's priority (@samp{A}, @samp{B} or @samp{C}) by editing
the line. @samp{#A} tasks are important. @samp{#B} are medium
priority. @samp{#C} are low priority. Whenever you save the file or
call @kbd{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:

@itemize
@item planner-task-in-progress @samp{o} (@kbd{C-c C-z})
@item planner-task-done @samp{X} (@kbd{C-c C-x})
@item planner-task-cancelled @samp{C} (@kbd{C-c C-S-x})
@item planner-task-delegated @samp{D}
@item planner-task-pending @samp{P}
@item planner-task-open @samp{_}
@end itemize

After changing the status using a function, look at the
@samp{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
@command{planner-update-task} to update the linked page.

To reschedule a task, call @command{planner-copy-or-move-task} (@kbd{C-c
C-c}) and choose a new date.  You can mark a region and type @kbd{M-x
planner-copy-or-move-region} to reschedule all the contained tasks to a
different date.  Enter @samp{nil} for the date if you don't want the
task or group of tasks to appear on any date page at all anymore. This
is a good way to ``de-schedule'' a task for the time being, but still
keep it linked to a plan page for possible future scheduling.

To change the plan page associated with a task, call
@command{planner-replan-task}.  Enter @samp{nil} for the plan page if
you don't want the task to appear on any plan page anymore. If you
precede the command with a prefix argument, the text of the original
plan page will appear in the prompt for easy editing.

Since the same task may exist on two or more pages, such as a date page
and a plan page, it is dangerous to edit the description of the task by
hand. You should not do it unless you want to make the exact same
changes on all its linked pages.

Instead of doing this by hand, you should use
@command{planner-edit-task-description}. This will prompt you for the
changes to the task description and then update all the other pages to
which the task is linked.  Or, you can just use
@command{planner-delete-task} to remove the task from both pages, and
then create it again with the new desired description.

To remind yourself to do tasks in a certain order, simply edit the
lines so that they're in the order you want.
@command{planner-raise-task} and @command{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.
Planner will maintain the groupings and only sort the tasks within
that group.

@subheading Functions

@defun planner-replan-task page-name
Change or assign the plan page for the current task.  @var{page-name}
is the new plan page for the task. Use
@code{planner-copy-or-move-task} if you want to change the date. With a
prefix, provide the current link text for editing.
@end defun

@defun planner-raise-task-priority
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).
@end defun

@defun planner-lower-task-priority
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).
@end defun

@defun planner-raise-task arg
Move a task up @var{arg} steps.  By default, @var{arg} is 1.
@end defun

@defun planner-lower-task  arg
Move a task down @var{arg} steps.  By default, @var{arg} is 1.
@end defun

@defun planner-edit-task-description description
Change the description of the current task, updating the linked page
if any.
@end defun

@defun planner-delete-task
Delete this task from the current page and the linked page.
@end defun

@defun 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 @code{planner-edit-task-description}
or @file{planner-id.el}.
@end defun

See @command{planner-install-extra-task-keybindings} for additional
task-related shortcuts.

@node Carrying Over Unfinished Tasks, Task Numbering, Modifying Tasks, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Carrying Over Unfinished Tasks
@cindex tasks, carrying over

Sometimes you won't be able to cross off all the tasks on your list.
Planner makes it easy for you to keep track of things you still have
to do by automatically rescheduling unfinished tasks from the past few
days. By default, the @command{plan} command searches for unfinished
tasks from the last three days and reschedules them onto today. If you
open Planner every day, this should cover weekends easily.

It's a good idea to start Planner whenever you start Emacs. That way,
Planner can help remind you about today's tasks, appointments, and other
things. To automatically start Planner whenever you start up Emacs, add
the following code to the end of your @file{~/.emacs}:

@example
(plan)
@end example

Now, every time you start Emacs (which should be more or less once a
day), you'll see today's page. If you don't finish all the tasks today,
you'll see them again tomorrow.

It's a good idea to start Planner every time you start Emacs so that
you get reminded about your task list. If you prefer to start Planner
manually, remember to call @kbd{M-x plan} every so often to make sure
that you don't forget any unfinished tasks. Safe in the knowledge that
Planner tasks won't slip through the cracks (unlike little slips of
paper that will invariably get mislaid), you can then get on with the
rest of your life.

If your increased productivity with Planner leads to a well-deserved
two-week vacation, then you'll need to tell Planner to search more days
for unfinished tasks. By using @kbd{M-x plan}, you can automatically
bring forward tasks over a given number of days or even scan all the
days since time immemorial. @kbd{C-u 15 M-x plan} reschedules all
unfinished tasks from the last 15 days. @kbd{C-u -1 M-x plan} checks all
of your past day pages for unfinished tasks.

Like everything else in Planner, you can adapt @kbd{M-x plan} to your
particular way of life. For example, if you find yourself starting up
Emacs and Planner every day--including weekends--because it's just so
much fun, you can set the @code{planner-carry-tasks-forward} to 1.
This can make your Emacs startup marginally faster. On the other hand,
if you normally start Emacs once a week, you can set it to 7 or 8. If
you're worried about tasks dropping off your radar, you can set it to
0. You can set the value of @var{planner-carry-tasks-forward} either
with @key{M-x customize-variable RET planner-carry-tasks-forward RET},
or by putting @code{(setq planner-carry-tasks-forward 3)} (replacing
@code{3} with the value appropriate for what you want) in your
@file{~/.emacs} file.

On the other hand, you might prefer to reschedule tasks yourself. If
you set @code{planner-carry-tasks-forward} to @code{nil}, then
@command{M-x plan} and @code{(plan)} will bring you to the most recent
page with unfinished tasks if there is no page for today. You can then
use @command{planner-copy-or-move-task} and
@command{planner-copy-or-move-region} to reschedule tasks. This is
probably more hassle than it's worth, though, so let Planner take care
of this for you.

@subheading Options

@defopt planner-carry-tasks-forward
If non-nil, carry unfinished tasks forward automatically.
If a positive integer, scan that number of days in the past.
If 0, scan all days for unfinished tasks.
If t, scan one day in the past (old behavior).
If nil, do not carry unfinished tasks forward.
@end defopt

@subheading Functions

@defun plan &optional force-days
Start your planning for the day, carrying unfinished tasks forward.

If @var{force-days} is a positive integer, search that many days in the
past for unfinished tasks.
If @var{force-days} is @code{0} or @code{t}, scan all days.
If @var{force-days} is @code{nil}, use the value of
@code{planner-carry-tasks-forward} instead, except t means scan only
yesterday

@end defun

@defun planner-copy-or-move-task date force
Reschedule the task for @var{date}. If @var{force} is non-nil, the
task is moved regardless of status. It also works for creating tasks
from a Note. Use @code{planner-replan-task} if you want to change the
plan page in order to get better completion.
@end defun

@defun planner-copy-or-move-region beg end date muffle-errors
Move all tasks from @var{beg} to @var{end} to @var{date}.
@code{planner-copy-or-move-region} will copy or move all tasks from
the line containing @var{beg} to the line just before @var{end}. If
@var{muffle-errors} is non-nil, no errors will be reported.
@end defun

@node Task Numbering, Task Ranks, Carrying Over Unfinished Tasks, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Task Numbering

By default, tasks are numbered according to their position on the
page.  Task numbers allow you to refer to tasks using Muse links.
For example, the @samp{#A1} task in @file{2004.08.16} can be referred to
as @samp{2004.08.16#A1}.

Note that task numbers change every time you re-sort and re-number tasks
with @code{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.

@subheading Options

@defopt 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.
@end defopt

@node Task Ranks, Grouping Tasks, Task Numbering, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Task Ranks
@cindex ranking tasks
@cindex tasks, ranking
@cindex @file{planner-rank.el}, using

@file{planner-rank.el} models Franklin Covey's Urgency and Importance
principle. When you think about a task, there are two aspects in
consideration: Urgency and Importance. You may want to do the most
urgent things first, like answering an email, or you may want to do
the most important things first, like reading this manual. Or much
better, balance Urgency and Importance and decide what to do.

@file{planner-rank.el} can help you balance.

Urgency and Importance are both measured by scores from 0-9. The
higher the score, the more you want to do it first. 9 stands for ``I
should have done this'' and 0 stands for ``I can forget this''.

If you are using the planner @ref{Deadlines} feature, the Urgency
score is automatically calculated from how many days are left to meet
the deadline. By default, it will score 9 if the task is overdue and 0
if the deadline is years away. Please refer to the docstring of
@code{planner-rank-deadline-urgency-map-list} for detail.

The task rank is calculated from Urgency and Importance scores. As
different people balance urgency and importance differently, a number
of @code{planner-rank-calculate-rank-*} functions are provided. The
algorithms vary from a simple average to something like a weighted
root mean square deviation.

The aggressive versions of these functions
(@code{planner-rank-calculate-rank-*-aggressive}) will make sure if
one of Urgency and Importance is high, the resulting rank will be high
as well. @code{planner-rank-calculate-rank-weighted-*} functions weigh
the Urgency and Important scores depending on
@code{planner-rank-importance-vs-urgency-factor}.

Call @code{planner-rank-test-algorithm} on each of the functions and
check the result tables to see which one you like most, and set it to
@code{planner-rank-rank-calculate-function}. Alternatively, accept the
defaults and tweak them when you get a better feel for ranking.

Once the Rank is calculated, the @ref{Task Priorities} will be
automatically reset. If the Rank is greater than or equal to
@code{planner-rank-priority-A-valve}, the task priority will be
@samp{A}, if the Rank is between @code{planner-rank-priority-A-valve}
and @code{planner-rank-priority-B-valve}, the priority will be @samp{B},
else it will be @samp{C}.

After setting the task importance and deadline, you can leave it as
is. As the deadline approaches, the task priority will automatically
be raised and the task re-colored to catch your eyes.

If you are using @code{planner-sort-tasks} (see @pxref{Making Files
Pretty}), you can set @code{planner-sort-tasks-key-function} to one of
@code{planner-sort-tasks-by-rank},
@code{planner-sort-tasks-by-importance}, and
@code{planner-sort-tasks-by-urgency}.

@subheading Options

@defopt planner-rank-change-hook
Functions to run after @code{planner-rank-change}.
@end defopt

@defopt planner-rank-priority-A-valve
Tasks with rank greater than or equal to this value will be set to
priority @samp{A}.
@end defopt

@defopt planner-rank-priority-B-valve
Tasks with rank greater than or equal to this value and less than
@code{planner-rank-priority-A-valve} will be set to priority
@samp{B}. Tasks with rank less than this value will be set to priority
@samp{C}.
@end defopt

@defopt planner-rank-deadline-urgency-map-list
Defines how to calculate the Urgency score according to how many days
are left to meet the deadline.
@end defopt

@defopt planner-rank-default-importance
Default importance value for newly added rank.
@end defopt

@defopt planner-rank-default-urgency
Default urgency value for newly added rank.
@end defopt

@defopt planner-rank-importance-vs-urgency-factor
How much do you think importance is more ``important'' than urgency.
This will be used in @code{planner-rank-calculate-rank-weighted-*}
functions.
@end defopt

@defopt planner-rank-rank-calculate-function
Define the function called to calculate rank.
@end defopt

@subheading Functions

@defun planner-rank-change &optional importance urgency
Set the Importance and Urgency of the current task.
@end defun

@defun planner-rank-update-current-task
Recalculate rank for the current task.
@end defun

@defun planner-rank-update-all
Recalculate rank for all tasks in the current page
@end defun

@defun planner-rank-update-all
Recalculate rank for all tasks in the current page
@end defun

@node Grouping Tasks,  , Task Ranks, Organizing Your Tasks
@comment  node-name,  next,  previous,  up
@subsubsection Grouping Tasks with planner-trunk.el
@cindex grouping tasks
@cindex tasks, grouping
@cindex @file{planner-trunk.el}, using

@file{planner-trunk.el} helps you automatically group tasks according
to a set of rules. It sorts and splits your tasks, adding a blank line
between groups of tasks. For example, if today's page looks like this:

@example
* Tasks

#B   _ Buy milk (GroceryShopping)
#B   _ Learn how to use planner-trunk (PlannerMode)
#B   _ Buy a notebook (Bookstore)
#B   _ Buy cereal (GroceryShopping)
#B   _ Set up my own planner-trunk rules (PlannerMode)
#B   _ Customize my stylesheet (MuseMode)
#B   _ Go for a health checkup (BetterHealth)
@end example

@noindent
then you might want to group the tasks into: planner and muse,
shopping list, and other items. If you set up the appropriate rules by
customizing @code{planner-trunk-rule-list}, @file{planner-trunk.el}
can automatically rewrite that section line this:

@example
* Tasks

#B   _ Learn how to use planner-trunk (PlannerMode)
#B   _ Set up my own planner-trunk rules (PlannerMode)
#B   _ Customize my stylesheet (MuseMode)

#B   _ Buy milk (GroceryShopping)
#B   _ Buy a notebook (BookstoreShopping)
#B   _ Buy cereal (GroceryShopping)

#B   _ Go for a health checkup
@end example

@noindent
In this case, you would set @code{planner-trunk-rule-list}
to @code{(("." nil ("PlannerMode\\|MuseMode" "Shopping")))}.

You can load @file{planner-trunk} with @kbd{M-x load-library RET
planner-trunk RET} or add @code{(require 'planner-trunk)}. If you're
not yet comfortable with Emacs Lisp, you can use @kbd{M-x
customize-variable RET planner-trunk-rule-list RET} to edit this rule
using an easy-to-use interface.

WARNING: Do not keep non-task information in the Tasks section.
planner-trunk will delete @strong{all} non-task lines from the Tasks
section of your plan page in the process of grouping the tasks.

After you set up @code{planner-trunk-rule-list}, use @command{M-x
planner-trunk-tasks} to try out your rules until you're satistfied.

If you want to do this automatically, you can use @code{(add-hook
'planner-mode-hook 'planner-trunk-tasks)} to trigger it automatically
whenever you open a Planner page.

@node Task Reports and Overviews,  , Organizing Your Tasks, More about Tasks
@subsection Task Reports and Overviews
@cindex task reports
@cindex task overviews
@cindex reports, task
@cindex overviews, task
@cindex reports, accomplishment
@cindex tasks, overview of

Planner provides a number of different ways to generate different
presentations of your tasks.

@menu
* Accomplishments::             planner-accomplishments.el
* Status Reports::              planner-report.el
* Task Overviews::              planner-tasks-overview.el
* <tasks> tag::             
* planner-registry::            Keep track of annotations
* planner-zoom::                View and navigate tasks by time period
@end menu

@node Accomplishments, Status Reports, Task Reports and Overviews, Task Reports and Overviews
@comment  node-name,  next,  previous,  up
@subsubsection Generating Daily Accomplishment Reports
@cindex reports, accomplishment
@cindex @file{planner-accomplishments.el}, using
@cindex tasks, overview of
@cindex task reports
@cindex reports, task
@cindex overviews, task
@cindex task overviews

You can use @file{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:

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

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

@itemize

There are currently two ways to use @file{planner-accomplishments.el}.

@item Displaying a temporary buffer

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

@item 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 @code{planner-accomplishments-section} to the name of the
section to rewrite (default: @samp{Accomplishments}). If you want
rewriting to be automatically performed, call
@code{planner-accomplishments-insinuate}. The accomplishments will be
rewritten whenever you save a planner page. If you want rewriting to
be manual, call @code{planner-accomplishments-update}.

@end itemize

@subheading Options

@defopt planner-accomplishments-section
Header for the accomplishments section in a plan page.
Used by @code{planner-accomplishments-update}.
@end defopt

@defopt planner-accomplishments-status-display
Alist of status-label maps also defining the order of display.
Used by @code{planner-accomplishments-format-table}.
@end defopt

@subheading Functions

@defun planner-accomplishments-insinuate ()
Automatically call @code{planner-accomplishments-update} when saving
tasks in @code{planner-mode} buffers.
@end defun

@defun planner-accomplishments-update ()
Rewrite @code{planner-accomplishments-section} with a summary of tasks
on this page.
@end defun

@defun planner-accomplishments-show ()
Display a buffer with the current page's accomplishment report.
@end defun

@node Status Reports, Task Overviews, Accomplishments, Task Reports and Overviews
@comment  node-name,  next,  previous,  up
@subsubsection Status Reports
@cindex status reports
@cindex reports, status
@cindex @file{planner-report.el}, using

@file{planner-report.el} creates a status report for a given timespan.
The report itself is just another Planner page in your planner
directory.  Once generated, it contains tasks and notes culled from
active project pages.  Tasks are only shown if they are incomplete or
were completed within the timespan.  Notes are shown if they were
created during the timespan.  Tasks and notes are grouped together under
a heading for their corresponding project.

The idea is you have one of these status reports generated periodically
(say, every couple of weeks).  Perhaps you use cron to run them
automatically and then mail you a reminder that they've been done.  Then
you can edit the page, adding verbiage where it is needed and removing
irrelevant items.  This editing process is as easy as editing any other
Planner page.  Finally, you can publish the page along with the rest of
your planner using @kbd{M-x muse-project-publish}.

If you use planner-authz.el, you can tell planner-report.el only to
consult project pages that a given list of users
(@var{planner-report-authz}) can access when generating the report.  For
example, if you're preparing a status report for your boss, add yourself
and him to @var{planner-report-authz}.  The resulting status report will
only contain information the two of you are supposed to have access to,
and the report itself will be similarly restricted.

@subheading Getting started

Add the following to your .emacs file:

@example
(require 'planner-report)
@end example

Then you can use the following command to generate a status report:

@example
M-x planner-report-generate
@end example

You will be prompted for a beginning and ending date, and then the
status report will be generated.  You can then edit it to your liking
and publish it just like you would the rest of your planner.

@subheading Options

@defopt planner-report-authz
List of users a status report should be restricted to.
When status reports are generated, only planner pages accessible
by these users will be consulted, and the resulting status report
will be similarly restricted.
@end defopt

@defopt planner-report-pretty-print-plan-pages
If non-nil, pretty print plan pages.
If nil, leave page names as-is.
This requires that @file{muse-wiki.el} be loaded to work properly.
@end defopt

@defopt planner-report-remove-task-numbers
Remove task numbers when generating status reports.
@end defopt

@defopt planner-report-replace-note-numbers
If non-nil, a string with which to replace note numbers when
generating status reports.
@end defopt

@defopt planner-report-unfinished-offset
If non-nil, the offset in days from the current date of
unfinished tasks to include in the status report.  If nil,
include all unfinished tasks.
@end defopt

@subheading Functions

@defun planner-report-generate begin end
Generate a status report spanning a period from @var{begin} to @var{end}.
@var{begin} and @var{end} are in the format YYYY.MM.DD.
@end defun

@node Task Overviews, <tasks> tag, Status Reports, Task Reports and Overviews
@comment  node-name,  next,  previous,  up
@subsubsection Seeing an Overview of Tasks
@cindex tasks, overview of
@cindex task reports
@cindex reports, task
@cindex overviews, task
@cindex task overviews
@cindex @file{planner-tasks-overview.el}, using

You can see a list of tasks with @file{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

@var{date} | @var{link} | @var{priority} @var{status} | @var{task-description}

@subheading Functions

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

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

Once in a @code{planner-tasks-overview} buffer, you can use
the keyboard shortcut @key{o} to change the overview period.
@end defun

You can sort the task display with the following functions:

@defun planner-tasks-overview-sort-by-date
Sort the tasks by date. Keyboard shortcut: @key{1}
@end defun

@defun planner-tasks-overview-sort-by-plan
Sort the tasks by associated plan page. Keyboard shortcut: @key{2}
@end defun

@defun planner-tasks-overview-sort-by-priority
Sort the tasks by priority. Keyboard shortcut: @key{3}
@end defun

@defun planner-tasks-overview-sort-by-status
Sort the tasks by status. Keyboard shortcut: @key{4}
@end defun

You can jump to linked tasks with

@defun planner-tasks-overview-jump other-window
Display the current task. If a prefix argument is supplied, show the
task in another window. Keyboard shortcut: @key{j}
@end defun

@defun planner-tasks-overview-jump-other-window
Display the current task in another window. Keyboard shortcut: @kbd{C-u j}
@end defun

You can view a summary of the tasks in your plan pages with

@defun planner-tasks-overview-show-summary &optional file-list
Count unscheduled, scheduled, and completed tasks for FILE-LIST. If
called with an interactive prefix, prompt for the plan page(s) to
display. Load @file{planner-multi.el} to be able to specify multiple
pages.
@end defun

@subheading Keys

@key{TAB}, @kbd{SHIFT-TAB} and @key{RET} navigate links in the usual
fashion.

@node <tasks> tag, planner-registry, Task Overviews, Task Reports and Overviews
@subsubsection <tasks> tag
@cindex <tasks> tag
@cindex task reports
@cindex reports, task
@cindex overviews, task
@cindex task overviews
@cindex tasks, overview of

@samp{<tasks>} is replaced by a report of tasks over all day pages in
published pages (@pxref{Publishing}).

@example
All incomplete tasks

<tasks status="^X">

All completed tasks

<tasks status="X">

All tasks

<tasks>
@end example

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

@node planner-registry, planner-zoom ,<tasks> tag, Task Reports and Overviews
@comment  node-name,  next,  previous,  up
@section planner-registry
@cindex @file{planner-registry.el}, using

The @file{planner-registry} module provides a way to keep track of all
the URLs in your projects, and to list them depending on the current
buffer.  The URLs are defined in @code{muse-url-protocols} module from
Muse.

If a URL has been created by @code{planner-create-task-from-buffer},
going to that buffer and calling @code{planner-registry-show} will show
you where Planner put the URL.

@subheading Getting started

To begin using @file{planner-registry}, add the following to your
Planner configuration file.

@example
(require 'planner-registry)
(planner-registry-initialize)
@end example

You must put it after the place where Planner has been loaded in your
configuration file.

If you want the registry to be updated each time you save a Planner
file, add the following to your Planner configuration.

@example
(planner-registry-insinuate)
@end example

If you don't want to update the registry each time a file is written,
you can do it manually with @code{planner-registry-update}: it will
update the registry for saved Planner/Muse buffers only.

@file{planner-registry} does not define any keybindings by default.  Its
most useful interactive function is @code{planner-registry-show}.

@subheading Example usage

Say for example that you created a task from an e-mail.  Go to that
e-mail and call @code{planner-registry-show}: it will open a new buffer
displaying the files (in a muse links format) where a link to this
e-mail has been added.

@subheading Options

@file{planner-registry} defines the following options.

@defopt planner-registry-file
The file where @file{planner-registry} stores its URL registry.
@end defopt

@defopt planner-registry-min-keyword-size
The minimum size for keywords.
@end defopt

@defopt planner-registry-max-keyword-size
The maximum size for keywords.
@end defopt

@defopt planner-registry-max-number-of-keywords
The maximum number of keywords.
@end defopt

@defopt planner-registry-ignore-keywords
A list of keywords to ignore.
@end defopt

@defopt planner-registry-show-level
Level used by the @code{planner-registry-show} function.
0 means that this function shows only exact matches.
1 means that this function also shows descriptive matches.
2 (or more) means that this function also shows fuzzy matches.
@end defopt

@node planner-zoom, , planner-registry, Task Reports and Overviews
@comment  node-name,  next,  previous,  up
@section planner-zoom
@cindex @file{planner-zoom.el}, using
@cindex view, weekly
@cindex view, quarterly
@cindex view, monthly
@cindex view, yearly

When assessing where you stand in relation to the tasks you have set
out for yourself, you might want a way to survey those tasks in groups
divided by time periods, like by the week or by the month. You could
create all of these overview pages by hand, but if you like to have
this kind of overview frequently, you might find manually creating
such pages to be tedious and time consuming.

@file{planner-zoom} is an optional module designed to make it easy to
view your task information grouped by year, quarter, month, week or
day.

To install this module, just load it in your @file{.emacs} (or
@file{_emacs}):

@example
(require 'planner-zoom)
@end example

This module will recognize planner pages named according to the
following scheme:

@table @asis

@item year view
@file{2006.Year}

@item quarter view
@file{2006.Quarter2}

@item month view
@file{2006.January}

@item week view
@file{2006.January.Week3}

@item day view
@file{2006.01.02}

@end table

@subheading Keybindings

This module also adds key bindings that you can use when looking at a
Planner page to easily jump between the different time-period views.

@table @kbd

@item S-up
Move to the view corresponding to the time period one step larger than
the current one. For example, it moves from the weekly view to the
monthly view. It calls @code{planner-zoom-iup}.

@item S-down 
Move to the view corresponding to the time period one step smaller
than the current one. For example, it moves from the weekly view to
the daily view. It calls @code{planner-zoom-idown}.

@item S-left
Stay in the same time-period view as the current one, but move one
interval earlier. For example, it moves from @file{2006.January.Week3}
to @file{2006.January.Week2}. It calls @code{planner-zoom-iprev}.

@item S-right
Stay in the same time-period view as the current one, but move one
interval later. For example, it moves from @file{2006.January.Week3}
to @file{2006.January.Week4}. It calls @code{planner-zoom-inext}.

@end table

@subheading Example usage

Look at the page named @file{2006.January} and then hit @kbd{S-down}
which will show @file{2006.January.Week1}. Then hit @kbd{S-left} and
@kbd{S-right} to look at @file{2006.January.Week2},
@file{2006.January.Week3}, etc.

@subheading Advanced tips and options

You can use any prefix argument with @code{planner-zoom-iup} and
@code{planner-zoom-idown} to have the new view display in a window
other than the current one. This also works with a nonnumeric prefix
argument and @code{planner-zoom-inext} or @code{planner-zoom-iprev}.
For these two functions, a numeric prefix will specify the number of
intervals to move.

If you don't like the default patterns for naming the time-period view
pages, you can change them by customizing @code{planner-zoom-regexps}.

Some people believe weeks start with Sunday, and some believe they
start with Monday. To accommodate both of these colliding worldviews,
@code{planner-zoom-first-day-of-week} can be customized. Its default
value is @samp{1}, which is Monday. If you would prefer Sunday, change
it to @samp{0}. The month to which a week belongs is the month in
which the first day of the week falls.

@subheading Command reference

@defun planner-zoom-iup name other-window
Move to the next higher level in the hierarchy. With a prefix
argument, show the desired page in the other window.
@end defun

@defun planner-zoom-idown name other-window
Move to the next lower level in the hierarchy. If the current date is
within the higher-level time range, zoom to the lower level time range
that also contains today. Otherwise, just go to the first lower-level
time range. With a prefix argument, show the desired page in the other
window.
@end defun

@defun panner-zoom-inext name num other-window
Move to the next time range at the same level in the hierarchy. With a
numeric prefix argument, move by that number of time ranges. With a
non-numeric prefix argument, show the desired page in the other window.
@end defun

@defun planner-zoom-iprev name num other-window
Move to the previous time range at the same level in the hierarchy.
With a numeric prefix argument, move by that number of time ranges.
With a non-numeric prefix argument, show the desired page in the other
window.
@end defun

@node More about Notes, Making Files Pretty, More about Tasks, More about Planner
@section More about Notes
@cindex notes, more about

Planner 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 @samp{.#1}. If you would like to reverse this behavior,
look at @kbd{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:

@example
.#1 Headline (LinkedNote#1)
Text
@end example

You can jump to the linked note with
@command{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.

@subheading Functions

@defun planner-create-note page
Create a note to be remembered in @var{page} (today if @var{page} is
nil).  If @code{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.
@end defun

@defun planner-create-note-from-task
Create a note based on the current task and update the current task to
link to the note.
@end defun

@defun planner-renumber-notes
Update note numbering.
@end defun

@defun planner-jump-to-linked-note note-info
Display the note linked to by the current note or @var{note-info} if
non-nil.
@end defun

@defun planner-search-notes regexp limit
Return a buffer with all the notes returned by the query for
@var{regexp}.  If called with a prefix argument, prompt for
@var{limit} and search days on or after @var{limit}.
@end defun

The following sections include instructions for displaying,
manipulating, and navigating your notes efficiently.

@menu
* Using Allout Mode::           Quickly navigating your notes
* <notes>::                     Note headlines
* <past-notes>::                Index of past notes
* Note Indices::                planner-notes-index.el
@end menu

@node Using Allout Mode, <notes>, More about Notes, More about Notes
@subsection Using Allout Mode
@cindex Allout mode
@cindex notes, navigating
@cindex notes, formatting
@cindex notes, displaying

The format of the notes in Planner works well with Allout mode, which
provides helpful commands for navigating and formatting outlines. You
can, for example, hide the bodies of all the notes on a page so you can
see just their headlines. You can also jump easily from headline to
headline, skipping over the bodies in between.

The commands for using Allout mode vary depending on which Emacs
version you are using. In either case, type @kbd{M-x load-library
@key{RET} allout @key{RET}} to start. If you are using Emacs 22 or
later, type @kbd{M-x allout-mode @key{RET}}. If you are using an
earlier version of Emacs, type @kbd{M-x outline-mode @key{RET}}.

The exact commands then available to you differ depending on your
Emacs version, but you can view the commands and their keybindings by
typing @kbd{C-h m}. In Emacs 22 or later, they will start with
@command{allout-}, while in previous versions, they will start with
@command{outline-}.

For more information about using Allout mode, see @kbd{C-h f
allout-mode @key{RET}}.

@node <notes>, <past-notes>, Using Allout Mode, More about Notes
@subsection <notes>

@samp{<notes>} is replaced by a list of note headlines when the page
is published. For example, the notes tag in the following example will
be replaced by the two headlines when published. (@pxref{Publishing})

@example
<notes>

* Notes

.#1 This is a headline

and this is body text

.#2 This is another headline

and this is more body text
@end example

@samp{<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
@code{planner-day-page-template}.

@node <past-notes>, Note Indices, <notes>, More about Notes
@subsection <past-notes>

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

@example
All the notes I've taken in 2004:

<past-notes start="2004.01.01" end="2004.12.31">
@end example

@node Note Indices,  , <past-notes>, More about Notes
@comment  node-name,  next,  previous,  up
@subsection Note Indices
@cindex @file{planner-notes-index.el}, using
@cindex notes, indexing

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

@example
(require 'planner-notes-index)
@end example

Then you can use tags of the form:

@example
<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">
@end example

You can also use the following interactive functions:

@code{planner-notes-index}
@code{planner-notes-index-days}
@code{planner-notes-index-weeks}
@code{planner-notes-index-months}
@code{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:

@example
 .#1 Headline
@end example

The results are presented as a bulleted list.

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

If @var{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 @code{<planner-notes-index>} tags. You can also use
@code{planner-extract-note-headlines} in your own functions.

@subheading Functions

The following interactive functions are defined in
@file{planner-notes-index.el}:

@defun planner-notes-index &optional from to limit
Display a clickable notes index. If called from a Lisp program,
display only dates between @var{from} and @var{to}. With a prefix arg
@var{limit}, display only that number of entries.
@end defun

@defun planner-notes-index-days days
Display an index of notes posted over the past few @var{days}. The
list ends with the day of the current buffer or @code{planner-today}.
@end defun

@defun planner-notes-index-weeks weeks
Display an index of notes posted over the past few @var{weeks}. The
list ends with the week of the current buffer or
@code{planner-today}. Weeks start from Sunday.
@end defun

@defun planner-notes-index-months months
Display an index of notes posted over the past few @var{months}. The
list ends with the month of the current buffer or @code{planner-today}.
@end defun

@defun planner-notes-index-years years
Display an index of notes posted over the past few @var{years}. The
current year is included.
@end defun

@file{planner-notes-index.el} does not define any keybindings.


@node Making Files Pretty, Annotations, More about Notes, More about Planner
@section Making Files Pretty

By default, planner does a little bit of fancy reformatting when you
save a file. Tasks are sorted by priority (ABC) and status (_oP>XC) on
day pages. On plan pages, tasks are sorted by priority (ABC), status
(XC), and date. Undated tasks are sorted after dated tasks.

@subheading Options

@defopt planner-sort-tasks-key-function
Control task sorting. Some options include
@code{planner-sort-tasks-default-key},
@code{planner-sort-tasks-basic}, @code{planner-sort-tasks-by-date}, and
@code{planner-sort-tasks-by-link}.
@end defopt

@defopt planner-sort-undated-tasks-equivalent
This option controls the behavior of task sorting on plan pages.  By
default, the value @samp{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.
@end defopt

@defopt 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.
@end defopt

@defopt 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 @samp{2003.08.12#A1}. If you use this function, make sure
@code{planner-use-task-numbers} is non-nil so that new tasks are created
with task numbers.
@end defopt

@defopt 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.
@end defopt

@defopt 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 renumbered if you delete a
note in the middle. However, if you use a lot of cross-referencing,
note renumbering will break those links.
@end defopt

@subheading Functions

@defun planner-sort-tasks
Sort tasks according to planner-sort-tasks-key-function. By default,
sort tasks according to priority and position on day pages, and
according to status, priority, date, and position on plan pages.
@end defun

@defun planner-renumber-tasks
Update task numbering.
@end defun

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

@defun planner-fix-tasks
Sort, renumber and align tasks.
@end defun

@node Annotations, Interactive Lisp, Making Files Pretty, More about Planner
@comment  node-name,  next,  previous,  up
@section 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, Planner has a list of functions,
@code{planner-annotation-functions}. When you create a task from a
buffer, or remember a note from a buffer, Planner 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 @code{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 @samp{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
@samp{* Notes} section of your page instead.

@subheading Options

To change the behavior of annotations, customize the following options:

@defopt planner-annotation-functions
A list of functions tried in order by
@command{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 @strong{not} be annotated, return the
empty string @samp{""}.
@end defopt

@defopt 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
@code{planner-annotation-strip-directory} is non-nil, though, only the
base name of the file will be displayed.  For example, a link to
@samp{/foo/bar/baz} will be displayed as @samp{baz} and hyperlinked to
the file.
@end defopt

@defopt planner-annotation-use-relative-file
If t, always use relative filenames.
@code{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 the first directory of your Planner
project in @code{muse-project-alist}.  That is, the created link will be
of the form @samp{../../somefile} instead of
@samp{/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 your Plan pages and their
respective publishing directory.
@end defopt

@node Interactive Lisp, Publishing, Annotations, More about Planner
@comment  node-name,  next,  previous,  up
@section Interactive Lisp with planner-lisp.el
@cindex Lisp functions, using with Planner
@cindex interactive Lisp fuctions, using with Planner
@cindex @file{planner-lisp.el}, using

You can include interactive Lisp functions in your planner pages.

First, you need @file{planner-lisp.el}. Put this in your @file{.emacs}
(or @file{_emacs}):

@example
(require 'planner-lisp)
@end example

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

@example

[[lisp:/plan][Plan]]

@end example

This will be rendered as @samp{Plan}. Selecting the link will run the
@code{plan} function interactively.

You can also execute other Lisp expressions. For example:

@example
[[lisp:/(planner-goto (planner-expand-name "+7"))][Next week]]
@end example

@file{planner-lisp.el} does not provide any interactive functions or
keybindings.

@node Publishing, Experimental Functions, Interactive Lisp, More about Planner
@section Publishing
@cindex publishing

You can publish your planner files to a variety of different formats.
For example, you can publish your planner in HTML and put it on a
normal web server. No special server support is required. This gives
you an easy way to keep other people up to date on your tasks, keep a
web log, or simply organize information.

Published files are stored in the path specified by
@code{muse-project-alist} for your Planner project. Just copy the
contents of this directory to your web server, and you're all set! Of
course, publishing is completely optional.

Here are some more features related to publishing:

@menu
* Publishing Planner pages::    planner-publish.el
* Publishing Calendars::        planner-calendar.el
* Authz Access Restriction::    planner-authz.el
* RSS Publication::             Sharing notes with planner-rss.el
* iCal Task Publication::       Sharing tasks with planner-ical.el
* RDF Publication::             planner-rdf.el
@end menu

@node Publishing Planner pages, Publishing Calendars, Publishing, Publishing
@comment  node-name,  next,  previous,  up
@subsection Publishing Planner pages
@cindex publishing
@cindex @file{planner-publish.el}, using

Publishing works by providing Muse with the settings and environment for
Planner publishing.

First, make sure that you have set up a proper
@code{muse-project-alist} (@pxref{Creating Your Planner}).

Second, add:

@example
(require 'planner-publish)
@end example

to your @file{.emacs} (or @file{_emacs}).

To publish your entire Planner project, hit @kbd{C-c C-p}
(@code{muse-project-publish}). To publish just the current buffer, hit
@kbd{C-c C-t} (@code{muse-publish-this-file}).

To automatically publish files when you save them, add the following
code to your @file{~/.emacs} (or @file{_emacs}):

@example
(eval-after-load "muse-mode"
  (add-hook 'after-save-hook
            #'(lambda ()
                (when (planner-derived-mode-p 'muse-mode)
                  (muse-project-publish nil)))
            nil t))
@end example

@subheading Styles provided

The following publishing styles are available.

@table @code

@cindex publishing styles, planner-html
@item planner-html
Publish Planner pages to HTML.

@cindex publishing styles, planner-xhtml
@item planner-xhtml
Publish Planner pages to XHTML.

@cindex publishing styles, planner-xml
@item planner-xml
Publish Planner pages to XML.

@end table

@subheading Options provided

The following options may be customized to enhance your publishing
experience.

@table @code

@item planner-publish-markup-regexps
List of markup rules for publishing Planner pages.

@item planner-publish-markup-functions
Specify which function to use for publishing different kinds of markup.

@item planner-publish-markup-tags
A list of custom HTML-like tags to recognize when publishing.

@item planner-xml-markup-strings
Strings that are inserted to publish XML markup.

@item planner-xml-header
Header used when publishing Planner XML files.
This may be text or a filename.

@item planner-xml-footer
Footer used when publishing Planner XML files.
This may be text or a filename.

@item planner-html-markup-strings
Strings that are inserted to publish HTML markup.

@item planner-html-style-sheet
CSS stylesheet elements used in Planner HTML and XHTML files.
This can also be one or more @samp{<link>} tags.

@item planner-html-header
Header used when publishing Planner HTML files.
This may be text or a filename.

@item planner-html-footer
Footer used when publishing Planner HTML files.
This may be text or a filename.

@item planner-xhtml-header
Header used when publishing Planner XHTML files.
This may be text or a filename.

@item planner-xhtml-footer
Footer used when publishing Planner XHTML files.
This may be text or a filename.

@item planner-html-inner-header
Extra header section that can be embedded within
@code{planner-html-header} and @code{planner-xhtml-header}.

@item planner-html-inner-footer
Extra header section that can be embedded within
@code{planner-html-footer} and @code{planner-xhtml-footer}.

@item planner-publish-prepare-regexps
List of markup rules to apply before publishing a page with Planner.

@item planner-publish-finalize-regexps
List of markup rules to apply after publishing a page with Planner.

@end table

@node Publishing Calendars, Authz Access Restriction, Publishing Planner pages, Publishing
@comment  node-name,  next,  previous,  up
@subsection Publishing Calendars
@cindex calendar, publishing
@cindex @file{planner-calendar.el}, using

To publish calendars in your day pages, it is necessary to do two steps.

@itemize
@item Add @code{(require 'planner-calendar)} to your configuration.
@item Add a @samp{<calendar>} tag to either your header, footer, or
@var{planner-day-page-template}, depending on where you want it to
appear.
@end itemize

To display a calendar based on a different day (given here as DAYPAGE),
use @code{<calendar page="DAYPAGE">}.

To get arrows to previous and next months to show up, use
@code{<calendar arrows="t">}.  The text in
@var{planner-calendar-prev-month-button} and
@var{planner-calendar-next-month-button} will be used for the arrows to
the previous and next months, respectively.

By default, Muse will not display the arrows properly, due to
limitations in the special-escaping algorithm.  To work around this,
remove the @samp{&} rule from @var{muse-xml-markup-specials}, or from
@var{muse-html-markup-specials} if you are using the 3.02.6 version of
Muse.

It is also possible to create a symlink from the current day page to the
page name specified by @var{planner-calendar-today-page-name}.  To
accomplish this, add the following to your configuration.

@example
(eval-after-load "muse-publish"
  '(add-hook 'muse-after-publish-hook
             'planner-calendar-create-today-link))
@end example

@subheading Options

@defopt planner-calendar-prev-month-button
HTML text used for previous month buttons.
@end defopt

@defopt planner-calendar-next-month-button
HTML text used for next month buttons.
@end defopt

@defopt planner-calendar-day-header-chars
Number of characters to use for day column header names.
@end defopt

@defopt planner-calendar-today-page-name
Default name for published today page link.
@end defopt

@subheading Functions

@defun planner-calendar-create-today-link
Add this function to @code{muse-after-publish-hook} to
create a ``today'' soft-link to the newest published planner day page,
on operating systems that support POSIX @command{ln}.
@end defun

@node Authz Access Restriction, RSS Publication, Publishing Calendars, Publishing
@comment  node-name,  next,  previous,  up
@subsection Authz Access Restriction
@cindex @file{planner-authz.el}, using
@cindex Mason, restricting portions with
@cindex access, restricting

@file{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
(@url{http://www.cpan.org}).  Setting up HTML::Mason is
outside the scope of this document.  Make sure that it works before
trying out @file{planner-authz.el}.

@file{planner-authz.el} modifies the behavior of
@command{muse-project-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 @samp{<authz>} tag lets you
restrict access to arbitrary content as follows:

@example
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.
@end example

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

The @samp{#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
@samp{#authz}-protected page are also wrapped in Mason code on linked
pages. To add a @samp{#authz} directive to a Muse page, place
@samp{#authz} followed by a space-delimited list of users on one
line. For example:

@example
#authz ajk sacha
@end example

@subheading Getting started

Add the following to your .emacs file to cause @kbd{M-x
muse-project-publish} to automatically use planner-authz features.

@example
(require 'planner-authz)
@end example

@subheading Diary markup

If your pages have a section with diary entries maintained by
planner-appt.el (or by any other means), you can control access to these
entries.  First, customize @code{planner-section-tagnames} to map your
diary section ("* Schedule", in this example) to a tag called
"diary-section".  An example follows.

@example
(add-to-list 'planner-section-tagnames '("Schedule" . "diary-section"))
@end example

If the name of your diary section is "* Diary", you will not need to
customize @code{planner-section-tagnames} by default.

Then make sure the diary entries you want restricted contain a
corresponding plan page name in parentheses, as in the following
example.

@example
10:00 10:30 Meeting with boss (WorkStuff)
@end example

@subheading Options

@defopt planner-authz-project-default
Default access list for project pages (not day pages).  If a given
project page doesn't contain a @samp{#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 @samp{#authz} tags will also be
restricted to the users listed here.
@end defopt

@defopt 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.
@end defopt

@defopt planner-authz-day-task-default
Same as @kbd{planner-authz-day-note-default}, but for tasks.
@end defopt

@subheading Functions

@defun 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.
@end defun

@node RSS Publication, iCal Task Publication, Authz Access Restriction, Publishing
@comment  node-name,  next,  previous,  up
@subsection RSS Publication
@cindex @file{planner-rss.el}, using
@cindex notes, RSS
@cindex RSS

@file{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:

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

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

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

@subheading Options

@defopt planner-rss-base-url
Base absolute URL for published blog entries. Should include trailing
@samp{/}.
@end defopt

@defopt 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.
@end defopt

@defopt 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
@samp{(("." nil 10))} to ensure that all feeds are limited to the 10
most recent items.
@end defopt

@subheading Functions

@file{planner-rss.el} defines the following interactive functions:

@defun planner-rss-add-note @var{feed}
Export the current note using @code{planner-add-item}. If @var{feed}
is specified, add the entry to the specified file. Else, add the entry
to all matching RSS feeds specified by
@code{planner-rss-category-feeds}.
@end defun

@node iCal Task Publication, RDF Publication, RSS Publication, Publishing
@comment  node-name,  next,  previous,  up
@cindex @file{planner-ical.el}, using
@subsection iCal Publication

iCal is an Internet Engineering Task Force (IETF) standard for
calendaring and scheduling. @uref{http://www.ietf.org/rfc/rfc2445.txt}

You can export your tasks to the iCal format using
@file{planner-ical}. Add @code{(require 'planner-ical)} to your
@file{~/.emacs}. Then you can use @kbd{M-x planner-ical-export-page}
to display the iCal equivalent of tasks on a page, which you can then
save to a file.

To export today's tasks to a file in your publishing directory, add
the following to your @file{~/.emacs}.

@example
(planner-ical-export-file
 (planner-today)
 (expand-file-name
   "tasks.ics"
   (muse-style-element :path (car (cddr (muse-project planner-project))))))
@end example

@subheading Functions

@defun planner-ical-export-page page &optional file
Export PAGE's tasks in the iCal format.
If FILE is non-nil, results are saved to that file.
If FILE is nil, results are displayed in a `planner-ical-export-buffer'.
@end defun

@defun planner-ical-export-this-page
Display the tasks on the current page in iCal format.
@end defun

@node RDF Publication,  , iCal Task Publication, Publishing
@comment  node-name,  next,  previous,  up
@subsection RDF Publication
@cindex @file{planner-rdf.el}, using
@cindex RDF, publishing to

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

@example
(require 'planner-rdf)
(eval-after-load "muse-publish"
  '(progn
     (add-hook 'muse-after-publish-hook
               'planner-rdf-publish-file)
     (add-hook 'muse-after-publish-hook
               'planner-rdf-publish-index)))
@end example

@menu
* Publishing with planner-rdf::  
* planner-rdf Tags::            
* planner-rdf Usage Examples::  
@end menu

@node Publishing with planner-rdf, planner-rdf Tags, RDF Publication, RDF Publication
@subsubsection Publishing with planner-rdf

Planner-rdf is now included in the normal Planner publishing process.
Pressing @key{C-p} will create a .owl and a .rdf file for every planner
file. Additionally it creates an index, @file{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 @code{planner-rdf-directory} to the desired
location.

The generated files:

@itemize
@item
@file{index.rdf} - a collection with pointers to the
@file{<plan-page>.rdf} files.
@item
@file{<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.
@item
@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.
@end itemize

@node planner-rdf Tags, planner-rdf Usage Examples, Publishing with planner-rdf, RDF Publication
@subsubsection planner-rdf Tags

Besides the factual information, e.g. the task status or description,
planner-rdf extracts links (in the format @samp{[[...][...]]} or
@samp{[[...]]}) and tags (@samp{@{@{...:...}@}@}) 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 @samp{@{@{Tasks:198@}@}} -- can be
used to express abstract qualities. Some examples:

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

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.

@node planner-rdf Usage Examples,  , planner-rdf Tags, RDF Publication
@subsubsection Usage Examples

Report generation with OpenOffice

The Perl file @file{this-week.pl}
(@url{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 (@url{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:

@itemize
@item
Use @file{planner2protege.pl}
(@url{http://www.rainervolz.de/planner-rdf/planner2protege.pl}) to
combine all OWL files into a single one.
@item
Use CWM (@url{http://www.w3.org/2000/10/swap/doc/cwm.html}) to combine
schema and data, with @code{python cmw --rdf planner-rdf.owl
planner-data.owl --think --rdf >planner2.owl}
@end itemize

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

@node Experimental Functions,  , Publishing, More about Planner
@comment  node-name,  next,  previous,  up
@section Experimental Functions
@cindex @file{planner-experimental.el}, using
@cindex experimental functions, Planner

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 @file{planner-experimental.el} is
in your load path, and add this to your @file{.emacs} (or
@file{_emacs}):

@example
(require 'planner-experimental)
@end example

@subheading Functions

@file{planner-experimental.el} defines the following interactive
functions:

@defun planner-search-notes-next-match
Jump to the next matching entry.  Call after
@code{planner-search-notes}.
@end defun

@defun planner-search-notes-previous-match
Jump to the previous matching entry.  Call after
@code{planner-search-notes}.
@end defun

@defun planner-remove-duplicates
Remove duplicate tasks.
@end defun

@file{planner-experimental.el} does not define any keybindings.

@node Managing Your Information, Advanced Configuration, More about Planner, Top
@comment  node-name,  next,  previous,  up
@chapter Managing Your Information

Planner can be integrated with other Emacs and even some non-Emacs
programs by loading additional modules. You can pick and choose from
these modules, choosing those that work with programs you use and that
produce information you want to have included in your Planner pages.

@menu
* E-mail::                      Linking notes and tasks to messages
* Scheduling and Time::         Tracking appointments and where your time goes
* Finances::                    Display your account balances and more
* Contacts and Conversations::  BBDB and ERC
* Tracking Research and Resources::  The Web, bibliographies, and bookmarks
* Tracking Development::        
@end menu

@node E-mail, Scheduling and Time, Managing Your Information, Managing Your Information
@comment  node-name,  next,  previous,  up
@section E-mail

Planner can work together with several different Emacs e-mail
clients. If you load the appropriate module for the e-mail client you
use, then your notes and tasks can be annotated with information
pointing to the specific e-mail message you were reading when you
created that note or task. When you are looking at the note or task, you
will be able to jump straight to that message.

@menu
* Unix mail::                   Unix mailboxes: planner-unix-mail.el              
* Gnus::                        Gnus mail and news reader: planner-gnus.el
* VM::                          VM mail reader: planner-vm.el
* Wanderlust::                  Wanderlust mail reader: planner-wl.el
* MH-E::                        MH-E mail reader: planner-mhe.el
* Rmail::                       Rmail: planner-rmail.el
@end menu


@node Unix mail, Gnus, E-mail, E-mail
@comment  node-name,  next,  previous,  up
@subsection Unix mail
@cindex @file{planner-unix-mail.el}, using
@cindex mbox, using Planner with
@cindex Unix mail, using Planner with
@cindex mail client, using Planner with

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

@example
(require 'planner-unix-mail)
@end example

Unix mail URLs are of the form:

@example
;; mail://PATH/TO/INBOX/message-id
@end example

Annotations will be of the form:

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

@file{planner-unix-mail.el} does not define any interactive functions or
create any new keybindings.

@node Gnus, VM, Unix mail, E-mail
@comment  node-name,  next,  previous,  up
@subsection Gnus
@cindex Gnus, using Planner with
@cindex mail client, using Planner with, Gnus
@cindex @file{planner-gnus.el}, using

To use this module, make sure that it is in your load path and put
this in your @file{.emacs} (or @file{_emacs}):

@example
(require 'planner-gnus)
(planner-gnus-insinuate)
@end example

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:

@smallexample
#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]])
@end smallexample

This module also binds @kbd{C-c C-t} in the Gnus summary and article
views to the command to create a new task.

@file{planner-gnus.el} does not define any interactive functions.

For more information about Gnus, see @inforef{Top, The Gnus Newsreader,
gnus}.

@node VM, Wanderlust, Gnus, E-mail
@comment  node-name,  next,  previous,  up
@subsection VM
@cindex VM, using Planner with
@cindex mail client, using Planner with, VM
@cindex @file{planner-vm.el}, using

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

@example
(require 'planner-vm)
@end example

VM URLs are of the form:

@example
vm://path/to/inbox/message-id
@end example

Annotations will be of the form:

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

@file{planner-vm.el} does not define any interactive functions or
keybindings.


@node Wanderlust, MH-E, VM, E-mail
@comment  node-name,  next,  previous,  up
@subsection Wanderlust
@cindex Wanderlust, using Planner with
@cindex mail client, using Planner with, Wanderlust
@cindex @file{planner-wl.el}, using

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

@example
(require 'planner-wl)
@end example

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

@subheading Keys

To add keybindings to Wanderlust, call:

@example
(planner-wl-insinuate)
@end example

This binds @kbd{C-c C-t} to @command{planner-create-task-from-buffer}.

@node MH-E, Rmail, Wanderlust, E-mail
@comment  node-name,  next,  previous,  up
@subsection MH-E
@cindex MH-E, using Planner with
@cindex mail client, using Planner with, MH-E
@cindex @file{planner-mhe.el}, using

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

@example
(require 'planner-mhe)
@end example

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

@file{planner-mhe} does not define any interactive functions.

@node Rmail,  , MH-E, E-mail
@comment  node-name,  next,  previous,  up
@subsection Rmail
@cindex Rmail, using Planner with
@cindex mail client, using Planner with, Rmail
@cindex @file{planner-rmail.el}, using

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

@example
(require 'planner-rmail)
@end example

Rmail URLs are of the form:

@example
rmail://message-id
@end example

Annotations will be of the form:

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

@file{planner-rmail.el} does not define any interactive functions or
create any new keybindings.

For more information about Rmail, see @inforef{Rmail, Reading Mail With
Rmail, Emacs}.

@node Scheduling and Time, Finances, E-mail, Managing Your Information
@comment  node-name,  next,  previous,  up
@section Scheduling and Time

@menu
* Diary::                       Using the Emacs diary: planner-diary.el
* Appointments::                Appointments in plan pages: planner-appt.el
* Timeclock::                   Time tracking: planner-timeclock.el
* schedule.el::                 Project completion: planner-schedule.el
@end menu


@node Diary, Appointments, Scheduling and Time, Scheduling and Time
@comment  node-name,  next,  previous,  up
@subsection Diary
@cindex diary, using Planner with
@cindex @file{planner-diary.el}, using

If you use Emacs's diary feature, Planner-Diary could be helpful for
you. It puts all diary entries for the current day in the @samp{*
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. (@pxref{Diary, , , Emacs, GNU Emacs
Manual})

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

@example
(require 'planner-diary)
@end example

@file{planner-diary.el} needs @command{fancy-diary-display}.  To use
@command{fancy-diary-display}, add this to your @file{.emacs} (or
@file{_emacs}):

@example
(add-hook 'diary-display-hook 'fancy-diary-display)
@end example

You can use Planner-Diary in two different ways:

@enumerate

@item
If you want the saved files to contain your entries and not just a line
of Lisp, add the following lines to your @file{.emacs} (or @file{_emacs}):

@example
(setq planner-diary-use-diary t)
(planner-diary-insinuate)
@end example

You should also customize or set @code{planner-day-page-template} to
include a @samp{* Diary}:

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

@kbd{C-c C-e} updates the diary sections.  @kbd{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 @samp{Diary} section in the buffer.

@item
(GNU EMACS ONLY) You can put the following line of Lisp code in your
day plan pages to display your diary entries:

@example
<lisp>(planner-diary-entries-here)</lisp>
@end example

You can do this automatically for all day plan pages:

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

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

@end enumerate

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

These diary sections are only intended for display. Editing them will
not affect your diary file. If you want to add entries to your diary,
you should use the usual Emacs diary and calendar methods for doing
that, or call @code{planner-diary-add-entry}.

If you want to use the Cal-Desk package, simply follow the instructions
in @file{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 support
of Planner. (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) To get
Calendar integration, add this to your @file{.emacs} (or @file{_emacs}):

@example
(planner-insinuate-calendar)
@end example

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

@cindex planner2diary.py, using
If you want to import Planner entries into your Diary file, the
@file{planner2diary.py} script will accomplish this for you.  To use it,
execute @code{planner2diary.py} on the command line, specifying your
planner directory as the first and only argument.

@subheading Options

@defopt 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.
@end defopt

By default, planner-diary lists only the appointments you have on that
day. If you want the date headers included even when showing the diary
entries for a single day, set planner-diary-include-all-output to
non-nil.

@defopt planner-diary-include-all-output-flag
Non-nil means don't omit any data when copying diary entries into day
pages.
@end defopt

@subheading Functions

@file{planner-diary.el} defines the following interactive functions:

@defun planner-diary-add-entry date time text
Prompt for a diary entry to add to @code{diary-file} on @var{date}.
Uses @code{planner-annotation-functions} to make hyperlinks.
@var{time} and @var{text} are used in the description."
@end defun

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

@defun 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 @var{force} is nil, don't do anything. If
@var{force} is non-nil, insert a diary section even if there is no
@code{planner-diary-string} in the buffer.
@end defun

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

@defun 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 @var{force} is nil, don't do
anything.  If @var{force} is non-nil, insert a diary appointments
section even if there is no @code{planner-diary-appts-string} in the
buffer.
@end defun

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

@defun 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 @var{force} is nil, don't do
anything.  If @var{force} is non-nil, insert a cal-desk appointments
section even if there is no @code{planner-diary-cal-desk-string} in the
buffer.
@end defun

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

@defun 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 @var{force} is nil, don't do
anything.  If @var{force} is non-nil, insert a public appointments
section even if there is no @code{planner-diary-public-string} in the
buffer.
@end defun

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

@defun 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 @var{force} is nil, don't do
anything.  If @var{force} is non-nil, insert a private appointments
section even if there is no @code{planner-diary-private-string} in the
buffer.
@end defun

@defun planner-diary-insert-all-diaries force
Update all diary sections in a day plan file.  If @var{force} is
non-nil, insert a diary section even if there is no section header.  It
only inserts diaries if the corresponding @code{planner-diary-use-}*
variable is @samp{t}.
@end defun

@defun 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 @var{force} is nil, don't do anything.  If @var{force} is
non-nil, insert a diary section even if there is no section header.  It
only inserts diaries if the corresponding @code{planner-diary-use-}*
variable is @samp{t}.
@end defun

@defun planner-diary-show-day-plan-or-diary
Show the day plan or diary entries for the date under point in calendar.
Add this to @code{calendar-move-hook} if you want to use it.  In that
case, you should also @command{remove-hook} @samp{planner-calendar-show}
from @code{calendar-move-hook}.
@end defun

@subheading Keys

@file{planner-diary.el} adds the following keybinding to Planner, if
@command{planner-diary-insinuate} is in your @file{.emacs} (or
@file{_emacs}):

@itemize

@item
@kbd{C-c C-e} updates the diary sections by calling
@code{planner-diary-insert-all-diaries-maybe}.

@end itemize

@menu
* Planner-Diary Advanced Features::  
@end menu

@node Planner-Diary Advanced Features,  , Diary, Diary
@comment  node-name,  next,  previous,  up
@subsubsection Planner-Diary Advanced Features
@cindex diary, using Planner with
@cindex @file{planner-diary.el}, 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.

@subheading Diary views

@cindex @file{planner-diary.el}, views
Currently Planner-Diary supports six different views of your diary
entries:

@enumerate
@item
Ordinary fancy diary display (what you get by pressing @kbd{d} in the
calendar buffer with @code{fancy-diary-display} switched on)

@item
Schedule/Appointments (all entries from 1 that have a time assigned to
them

@item
Diary without appts (1 without 2)

@item
cal-desk display (appts on top, non appts entries at bottom)

@item
A private diary (same as 1, but uses a different diary-file)

@item
A public diary (same as 1, but uses a different diary-file)
@end enumerate

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

@example
<lisp>(planner-diary-entries-here)</lisp>
@end example

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

@subheading Exporting Planner-specific Diary files

@cindex @file{planner-diary.el}, exporting entries
If you would like to export diary entries from your Planner pages to
separate Diary files, add @code{(require 'planner-export-diary)} to your
config.  The following steps describe the usage of the functions and
options contained in this file.

@enumerate

@item
Customize @code{planner-export-diary-file}.  The default value is
``~/diary.planner''.

@item
Add the following line to your main Diary file (default: ``~/diary'').

@example
#include ~/diary.planner
@end example

@item
Then, call @command{M-x planner-export-diary-future} whenever you want
future diary entries published. You can automatically publish entries by
adding either of the following to your .emacs.

@itemize

@item (planner-export-diary-future)
Publish future entries on startup.

@item (add-hook 'planner-mode-hook 'planner-export-diary-setup)
Publish future entries whenever you save a Planner file.

@end itemize

@end enumerate

@node Appointments, Timeclock, Diary, Scheduling and Time
@comment  node-name,  next,  previous,  up
@subsection Appointments
@cindex appointments
@cindex @file{planner-appt.el}, using

If you would like to use planner for your appointment alerts
instead of using the diary system, you might like to try
@file{planner-appt}.

According to your preferences, you may choose from two different
approaches. Appointments in task descriptions on today's plan
page are like this:

@example
#A   _ @@12:45 Do something (TaskPool)
@end example

@noindent
and appointments in today's schedule section are like this:

@example
* Schedule

  9:00 | 12:00 | Read Simmel's Philosophy of Money
@@12:45 |       | Do Something Else
@@13:00 | 14:00 | lunch
@end example

@noindent
You can even use both at the same time if you like.

@c Jim Ottaway <j.ottaway@lse.ac.uk>: Changed these kinds of heading
@c back to @unnumberedsec, but left the originals commented out in
@c case there was a good reason for the @strong formatting.

@c @noindent
@c @strong{Usage}
@unnumberedsubsubsec Usage

In the file where you configure Planner, add one of the following.

@itemize
@item
For task-based appointments: @code{(planner-appt-use-tasks)}
@item
For schedule-based appointments: @code{(planner-appt-use-schedule)}
@item
For both task- and schedule-based appointments:
@code{(planner-appt-use-tasks-and-schedule)}
@end itemize

@noindent
And finally if you want everything to be updated automatically add:

@example
(planner-appt-insinuate)
@end example

If you don't want to do the insinuation then you can call:

@example
M-x planner-appt-update
@end example

@noindent
after editing appointments on the page (note that this is not
necessary if you use tasks for the appointments and you don't edit
the task descriptions outside of @code{planner-edit-task-description}).

Try both methods; if you find that you prefer one over the
other, use one of the specific @code{planner-appt-use-} functions, as
there are some performance gains when using one method exclusively.

@menu
* Task-based Appointments::     
* Schedule-based Appointments::  
* Viewing Appointments::        
* Appointment Updating on Save::  
* Appointment and Calendar Integration::  
* Appointment Hooks::           
@end menu


@node Task-based Appointments, Schedule-based Appointments, Appointments, Appointments
@comment  node-name,  next,  previous,  up
@subsubsection Task-based Appointments
@cindex appointments, task-based
@cindex task-based appointments

A task has an appointment if it looks like this:

@example
#A   _ @@12:45 Do something (TaskPool)
@end example

@noindent
i.e., if it has @@ followed by a time at the beginning.  This means
the task is a regular appointment, and will not be carried forward
at the start of a new day.

Alternatively, it may have a !, like this:

@example
#A   _ !12:45 Do something else (TaskPool)
@end example

@noindent
This makes it a "nagging" appointment, which @emph{will} be carried
forward.  It will, however, lose the appointment time in the
process.

This may seem like a strange feature, but here is Henrik's
reasoning:

@quotation
Sometimes I have a task that I want to do at a certain time, so I
make it an appointment.  If I don't get around to doing it anyway,
I want it to be carried forward.  Basically, I sometimes use
appointments on tasks to annoy me until I get them done. :)
@end quotation

You can edit, move and delete tasks with the usual functions, and
appointments will be updated automatically.

You can update all task appointments on your page with

@example
M-x planner-appt-update
@end example

@c @noindent
@c @strong{Cyclic Entries}

@unnumberedsubsubsec Cyclic Entries
@cindex appointments, cyclic task entries

If you have @file{planner-cyclic} (@pxref{Cyclic Tasks}) loaded, entries
in your cyclical tasks file such as

@example
Friday #A _ @@12:45 staff meeting
@end example

@noindent
will appear every Friday and there will be an appointment alert set
up.

@c @noindent
@c @strong{Appointments Section}
@unnumberedsubsubsec Appointments Section
@cindex appointments, appointments section

You can have all task-based appointments copied to a separate section,
providing an overview of your appointments.

To do this, add

@example
(setq planner-appt-task-use-appointments-section-flag t)
@end example

@noindent to your configuration, or use @kbd{M-x customize-variable}.

The variable @code{planner-appt-task-appointments-section} is the name
of the section where the appointments will be copied.  By default, it is
set to @code{"Schedule"}, which means that task appointments will be
intermingled with schedule entries.

It is also a good idea to add the section you wish to use to
@code{planner-day-page-template} in order to control where that section
will appear on the page (otherwise it will appear at the top).

The format of the appointments follows that of a schedule; if you
don't like the way it looks, you can write something different and set
@code{planner-appt-format-appt-section-line-function} appropriately.
See the documentation for
@code{planner-appt-format-appt-section-line-function} for details.  It
should be fairly easy to see what needs to be done if you look at the
source for the default function (which is
@code{planner-appt-format-appt-section-line}).

If the section specified in
@code{planner-appt-task-appointments-section} is the same as the
schedule section specified in @code{planner-appt-schedule-section} (by
default @code{"Schedule"}), the default formatting function adds a
@samp{#} to the description so that one can visually distinguish
appointments from the task list from those that have been added to the
schedule.

@node Schedule-based Appointments, Viewing Appointments, Task-based Appointments, Appointments
@comment node-name,  next,  previous,  up
@subsubsection Schedule-Based Appointments
@cindex appointments, schedule-based
@cindex schedule-based appointments

Some scheduled tasks require reminders, others don't.  In this
schedule:

@example
* Schedule

9:00   | 12:00 | Read Simmel's Philosophy of Money
@@12:45          Do Something Else
@@13:00 | 14:00 | lunch
@@14:30 |       | Meet jrs to discuss his dissertation
@@16:00           Test Society seminar
18:00            go home
@end example

@noindent
those that have an @@ prefix will be added to the appointment
reminder list; the others will not.  The formats that are
recognized are fairly flexible, as you can see from the example.

If you change your schedule, you can update the appointment list
with

@example
M-x planner-appt-update
@end example

@noindent You can also have the schedule sorted as part of the update,
if you have this in your configuration:

@example
(setq planner-appt-sort-schedule-on-update-flag t)
@end example

@c @noindent 
@c @strong{Cyclical Entries}
@unnumberedsubsubsec Cyclical Entries
@cindex appointments, cyclic schedule entries

You can also have cyclical schedule entries(@pxref{Cyclic Tasks}) if you
add

@example
(planner-appt-schedule-cyclic-insinuate)
@end example

@noindent to your configuration.

If you put an entry in your cyclical task file like this

@example
Friday @@12:45 | 13:45 | Staff Meeting
@end example

@noindent
then it will appear in your schedule every Friday, and an
appointment alert will be set up.

@node Viewing Appointments, Appointment Updating on Save, Schedule-based Appointments, Appointments
@comment  node-name,  next,  previous,  up
@subsubsection Viewing Appointments
@cindex appointments, viewing

The command @command{planner-appt-show-alerts} will show all appointment
alerts currently scheduled.

@subheading Functions

There are two commands that show appointments in the future; the one
displays them in a pop-up buffer, the other puts the information into
the current day page.

@deffn {Command} planner-appt-forthcoming-display &optional days
Display a buffer of appointments for today and the next
@var{days}. Optional prefix argument @var{days} is the number of days
ahead to look. Its default value is defined by
@code{planner-appt-forthcoming-days}.
@end deffn

@deffn {Command} planner-appt-forthcoming-update-section &optional days
In today's plan page, add or update a list of forthcoming
appointments. Optional prefix argument @var{days} is the number of
days ahead to look. Its default value is defined by
@code{planner-appt-forthcoming-days}.  The section heading to use is
defined by @code{planner-appt-forthcoming-appt-section}.
@end deffn

@subheading Options

@defopt planner-appt-forthcoming-days
The number of days to look ahead for forthcoming appointments.  The
default value is seven days.
@end defopt

@defopt planner-appt-forthcoming-appt-section
The name of the section to use for inserting a list of forthcoming
appts.  The default value is @code{"Forthcoming Appointments"}.
@end defopt

@defopt planner-appt-forthcoming-show-day-names-flag
When non-nil (the default), day names will be shown in forthcoming
appointments.
@end defopt

@defopt planner-appt-forthcoming-repeat-date-string
String to insert for repeated dates.

When there are multiple appointments for a date, the date is inserted
in the first appointment and the others have this string in their date
cell.

If the string consists of anything other than whitespace, then a link
to the day page for the appoinment is created.
@end defopt

@defopt planner-appt-forthcoming-look-at-cyclic-flag
When non-nil, find forthcoming appointments in the cyclic diary file
(@pxref{Cyclic Tasks}) as well as in plan pages. Default is @samp{t}.
@end defopt

@node Appointment Updating on Save, Appointment and Calendar Integration, Viewing Appointments, Appointments
@comment  node-name,  next,  previous,  up
@subsubsection Appointment Updating on Save
@cindex appointments, updating on save

@subheading Options

@defopt planner-appt-update-appts-on-save-flag
When non-nil, update appointment reminders whenever today's plan page is
saved. Default value is @samp{nil}.
@end defopt

@node Appointment and Calendar Integration, Appointment Hooks, Appointment Updating on Save, Appointments
@comment  node-name,  next,  previous,  up
@subsubsection Appointment and Calendar Integration

Not strictly part of appointment handling, but if one isn't using
the diary, marking dates with plan pages seems to make sense.

@subheading Functions

@defun planner-appt-calendar-insinuate
Add a hook to diary display so that dates in the calendar that have day
pages are highlighted
@end defun

@node Appointment Hooks,  , Appointment and Calendar Integration, Appointments
@comment  node-name,  next,  previous,  up
@subsubsection Appointment Hooks

@subheading Options

@defvr {Hook} planner-appt-update-hook
Hook run after @code{planner-appt-update} has updated the appointment
list.
@end defvr

@node Timeclock, schedule.el, Appointments, Scheduling and Time
@comment  node-name,  next,  previous,  up
@subsection Timeclock
@cindex @file{planner-timeclock.el}, using
@cindex @file{planner-timeclock-summary.el}, using
@cindex @file{planner-timeclock-summary-proj.el}, using
@cindex timeclock, using Planner with

This module allows you to clock in and clock out of your projects
(@pxref{Time Intervals, , , Emacs, GNU Emacs Manual}) You can also
generate reports with the @code{<timeclock-report>} tag. You may want to
read the ``Keeping Track of Time'' page to see how you can use
planner-timeclock to produce detailed reports;
@xref{Keeping Track of Time}.

@file{timeclock.el} is part of GNU Emacs. If you are using XEmacs,
please use the version of @file{timeclock.el} that comes with Planner in
the @file{contrib} directory.

With @file{planner-timeclock.el} loaded,
@command{planner-task-in-progress} clocks in a task.  To clock out,
use @command{planner-task-done} or @command{timeclock-out}.

@file{planner-timeclock.el} defines the following keybindings:

@itemize
@item @kbd{C-c C-i}: @code{planner-task-in-progress}.
@item @kbd{C-c C-o}: @code{timeclock-out}.
@item @kbd{C-c C-T C-i}: @code{planner-timeclock-in}. (XEmacs)
@item @kbd{C-c C-T C-o}: @code{timeclock-out}. (XEmacs)
@item @kbd{C-c C-S-t C-i}: @code{planner-timeclock-in}. (GNU Emacs)
@item @kbd{C-c C-S-t C-o}: @code{timeclock-out}. (GNU Emacs)
@end itemize

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

Here is a sample report:

@example
Project               |     Time| Ratio| Task
PlannerMaintenance    |  0:03:58|  1.1%| Merge doc patch
                      |  0:17:09|  5.0%| Track down subdirectories
                      |  0:18:11|  5.3%| Merge planner-timeclock-summary-proj.el
               Total: |  0:39:18| 11.4%|
JapanCaseStudy        |  2:37:56| 45.6%| Prototype search result page
                      |  0:31:50|  9.2%| Update design documents
               Total: |  3:09:46| 54.8%|
ChristmasLetter       |  1:46:37| 30.8%| Write and send my Christmas letters
               Total: |  1:46:37| 30.8%|
LinuxPeople           |  0:10:29|  3.0%| Send questions for Linux in Education
               Total: |  0:10:29|  3.0%|
@end example

If you add @code{(require 'planner-timeclock-summary)} to your
@file{~/.emacs}, you can then use it in two ways.

@itemize

@item Display a temporary buffer

Call @code{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.

To review tasks over a date range, use
@code{planner-timeclock-summary-show-range}. You can use a regexp or a
function to filter tasks by calling
@code{planner-timeclock-summary-show-range-filter}.

@item 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 @code{planner-timeclock-summary-section}
(default: @samp{"Timeclock"}) to your @code{planner-day-page-template}.

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

@file{planner-timeclock-summary-proj.el} produces task / time
breakdowns on plan pages. Reports are of the form:

@example
TASK 0 | duration
TASK 1 | duration
 TOTAL | duration.
@end example

To use, add @code{(require 'planner-timeclock-summary)} to your
@file{~/.emacs}. Call @code{planner-timeclock-summary-proj-current}
from a project page. The report is inserted at the current position in
the buffer. The function @code{planner-timeclock-summary-proj-section}
does the same but the report is inserted inside a section called
@samp{* Report}.

@node schedule.el,  , Timeclock, Scheduling and Time
@comment  node-name,  next,  previous,  up
@subsection @file{schedule.el}
@cindex @file{planner-schedule.el}, using
@cindex @file{schedule.el}, using Planner with

@file{planner-schedule.el} allows you to project task completion time.
Tasks should be of the form:

@example
#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
@end example

@file{schedule.el} is included with Planner in the @file{contrib}
directory, but you can alternatively get it from
@url{http://www.newartisans.com/johnw/Emacs/schedule.el} if desired.

@file{schedule.el} provides a single Lisp function,
@code{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:

@enumerate

@item
If @file{timeclock.el} is being used, the amount of time left in the
current work day (@code{timeclock-workday-remaining})
(@pxref{Time Intervals, , , Emacs, GNU Emacs Manual})

@item
The amount of time in each work day (@code{schedule-workday})

@item
The definition of a work week (@code{schedule-week})

@item
Any holidays defined in the Emacs calendar
(@pxref{Holidays, , , Emacs, GNU Emacs Manual})

@item
Any appointments in the Emacs diary
(@pxref{Appointments, , , Emacs, GNU Emacs Manual})

@end enumerate

Taking all of the ``block out'' periods into account,
@code{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:

@example

  (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)))

@end example

To call this function, do:

@example

(compute-completion-times 3600 7200 3600)

@end example

@subheading Keys

@file{planner-schedule.el} defines the following keybindings:

@kbd{C-c RET} is bound to @command{planner-schedule-show-end-project}.
@kbd{C-c C-m} is also bound to
@command{planner-schedule-show-end-project}.

In XEmacs, @command{planner-schedule-show-end-project} is bound to
@kbd{C-c C-T c-e} and @kbd{C-c C-S-t C-e}.

@subheading Functions

@file{planner-schedule.el} defines the following interactive
functions:

@defun planner-schedule-show-end-project
Display the estimated project completion time.
@end defun

@file{schedule.el} does not define any interactive functions, or
keybindings.

@node Finances, Contacts and Conversations, Scheduling and Time, Managing Your Information
@comment  node-name,  next,  previous,  up
@section Finances
@cindex finances

Currently, Planner provides one module dedicated to tracking your
finances. This module works with a program called Ledger.

@menu
* Ledger::                      Personal finances: planner-ledger.el
@end menu

@node Ledger,  , Finances, Finances
@comment  node-name,  next,  previous,  up
@subsection Ledger
@cindex finances
@cindex @file{planner-ledger.el}, using
@cindex @file{ledger}, using Planner with

@file{planner-ledger.el} provides integration between planner and John
Wiegley's ledger accounting program, which can be found at
@url{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
@code{planner-ledger-balance-regexp} and
@code{planner-ledger-pending-regexp}. Example:

@example
* Tasks

* Ledger

** Pending transactions

* Notes

@end example

You can manually update ledger sections with the
@command{planner-ledger-insert-maybe} command.

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

@example
(add-hook 'planner-goto-hook 'planner-ledger-insert-maybe)
@end example

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

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

@subheading Options

@defopt planner-ledger-balance-accounts
List of accounts to be included or excluded from the balance overview.
@samp{+} includes all matching accounts, and @samp{-} excludes
matching accounts.  See the documentation for
@command{ledger-run-ledger} for more details.
@end defopt

@defopt planner-ledger-balance-regexp
Regular expression matching section for ledger balance.  Do not store
other data in this section, as it will be overwritten.
@end defopt

@defopt planner-ledger-pending-regexp
Regular expression matching section for ledger balance.  Do not store
other data in this section, as it will be overwritten.
@end defopt

@defopt planner-ledger-payment-task-regexp
Regular expression matching special ledger tasks.
@end defopt

@subheading Functions

@defun planner-ledger-insert-maybe
Update any ledger sections on the current page.
@end defun

@defun planner-ledger-add-entry-from-task
Create a ledger entry based on the task at point.  Task should match
@code{planner-ledger-payment-task-regexp}.
@end defun

@node Contacts and Conversations, Tracking Research and Resources, Finances, Managing Your Information
@comment  node-name,  next,  previous,  up
@section Contacts and Conversations
@cindex contacts
@cindex conversations

Planner has two modules available for keeping track of contact and
conversation information. The first uses the Big Brother Database
(BBDB), and the second uses Emacs Relay Chat (ERC). BBDB is a full
contact database. ERC is a client for chatting online on Internet Relay
Chat (IRC) networks. The ERC module for Planner will help you keep
track of online conversations you have if you use ERC for those
conversations, but does not by itself store contact information other
than the time you had the conversation, the network and channel you were
on when you had it, and maybe who you had it with. If you are looking
for a way to manage your full address book, then @file{planner-bbdb.el}
in combination with BBDB is what you are looking for.

@menu
* BBDB::                        Contacts: planner-bbdb.el
* Emacs Relay Chat::            Internet Relay Chat: planner-erc.el
@end menu

@node BBDB, Emacs Relay Chat, Contacts and Conversations, Contacts and Conversations
@comment  node-name,  next,  previous,  up
@subsection BBDB
@cindex @file{planner-bbdb.el}, using
@cindex BBDB, using Planner with

@file{planner-bbdb.el} allows you to refer to your contacts easily
from within a planner page. @inforef{Top, the BBDB Manual, bbdb}.

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

@file{planner-bbdb.el} does not define any interactive functions, or
keybindings.

@node Emacs Relay Chat,  , BBDB, Contacts and Conversations
@comment  node-name,  next,  previous,  up
@subsection Emacs Relay Chat
@cindex @file{planner-erc.el}, using
@cindex ERC, using Planner with
@cindex Emacs Relay Chat, using Planner with
@cindex IRC, using Planner with
@cindex Internet Relay Chat, using Planner with

To use planner-erc, place @file{planner-erc.el} in your load path
and add this to your @file{.emacs} (or @file{_emacs}):

@example

(require 'planner-erc)

@end example

IRC URLs may be of the following forms.

@example
irc://server/nick,isnick
irc://server/#channel
irc://server
@end example

Annotations will be in the following forms.

@example
[[irc://server/nick,isnick][Chat with nick on server#channel]]
[[irc://server/nick,isnick][Chat with nick on server]]
[[irc://server/#channel][Chat on server#channel]]
[[irc://server][Chat on server]]
@end example

@file{planner-erc.el} does not define any interactive functions, or
keybindings.

@node Tracking Research and Resources, Tracking Development, Contacts and Conversations, Managing Your Information
@comment  node-name,  next,  previous,  up
@section Tracking Research and Resources

Planner provides three modules for keeping track of information
involving three specific tools: w3m, BibTeX, and @file{bookmark.el}.

@menu
* W3m::                         Web browser: planner-w3m.el
* BibTeX::                      Bibliographies: planner-bibtex.el
* Bookmark::                    Bookmarks: planner-bookmark.el
@end menu

@node W3m, BibTeX, Tracking Research and Resources, Tracking Research and Resources
@comment node-name,  next,  previous,  up
@subsection W3m
@cindex @file{planner-w3m.el}, using
@cindex w3m, using Planner with

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

@file{planner-w3m.el} does not define any interactive functions, or
keybindings.

@node BibTeX, Bookmark, W3m, Tracking Research and Resources
@comment node-name,  next,  previous,  up
@subsection BibTeX
@cindex @file{planner-bibtex.el}, using

BibTeX URLs are of the form @samp{bibtex:file/name:key}.

@file{planner-bibtex.el} does not define any interactive functions.

@node Bookmark,  , BibTeX, Tracking Research and Resources
@comment  node-name,  next,  previous,  up
@subsection Bookmark
@cindex bookmarks
@cindex @file{bookmark.el}, using Planner with
@cindex @file{planner-bookmark.el}, using

@file{planner-bookmark.el} uses the @file{remember} package to create a
note whenever you create a bookmark (see @inforef{Bookmarks, Bookmarks,
Emacs}). For more information about @file{remember}, please check out

@itemize
@item
@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} -
EmacsWiki.org page
@item
@uref{http://sacha.free.net.ph/notebook/doc/dev/remember/remember.html}
- Online info documentation
@end itemize

Configure remember according to the instructions in
@file{remember-planner.el} so that notes are saved to your planner
pages.

@defopt planner-bookmark-take-note-after-set-bookmark-flag
Non-nil means show a @code{remember} buffer after setting a new
bookmark.
@end defopt

When you create a bookmark, Emacs will open a buffer for your notes.
@kbd{C-c C-c} saves the buffer to today's page. If you don't want to
save a note, you can kill the buffer.

Bookmark URLs are of the form @samp{bookmark://bookmark-name}.

@file{planner-bookmark.el} does not define any interactive functions.

@node Tracking Development,  , Tracking Research and Resources, Managing Your Information
@comment  node-name,  next,  previous,  up
@section Tracking Development
@cindex version control, using Planner with

Planner has three modules geared toward programmers. Two modules deal
with version control and integrating information from those projects
into the planner page. One module deals with the Gnats bug-tracking
system.

@menu
* Log Edit::                    Changelogs: planner-log-edit.el
* PSVN::                        svn changesets: planner-psvn.el
* XTLA::                        TLA changesets: planner-xtla.el
* Gnats::                       Gnats: The GNU bug reporting system
@end menu

@node Log Edit, PSVN, Tracking Development, Tracking Development
@comment  node-name,  next,  previous,  up
@subsection Log Edit
@cindex cvs, using Planner with
@cindex @file{planner-log-edit.el}, using
@cindex version control, using Planner with

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

You can load the module with @code{(require 'planner-log-edit)}. When
you load the module, @code{planner-log-edit-add-note} will be added to
@code{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. (@pxref{Version
Control, , , Emacs, GNU Emacs Manual})

@subheading Options

@defopt planner-log-edit-include-files-flag
Non-nil means include a list of committed files in the note.
@end defopt

@defopt 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.
@end defopt

@file{planner-log-edit.el} does not define any interactive functions.

@node PSVN, XTLA, Log Edit, Tracking Development
@comment  node-name,  next,  previous,  up
@subsection PSVN
@cindex PSVN
@cindex @file{planner-psvn.el}, using
@cindex Subversion, integration with

This module enables you to refer to your Subversion (svn) changesets
easily from within a Planner page, and to have your svn commits recorded
automatically as notes in your planner.

You must also have @file{psvn.el}, which is often packaged with
Subversion in GNU/Linux distributions.

You can then load the module by adding @code{(require 'planner-psvn)} to
your @file{~/.emacs}.

Once the module is loaded, Planner will pick up annotation information
from any psvn *svn-log-view* buffer. If you create a task or note while
in such a buffer, that task will have a hyperlink you can follow to
return to the changeset later.

These hyperlinks are of the form
@samp{psvn://http://my.svn-repos.at/svn/project1/trunk@@39}

Additionally, you can have notes for your commits automatically
generated. Set @var{planner-psvn-log-edit-notice-commit-function} to t
to enable this.

By default, these commit notes will include a list of the files
modified. If you would prefer to have this list not included, set
@var{planner-psvn-log-edit-include-files-flag} to nil.

@node XTLA, Gnats, PSVN, Tracking Development
@comment  node-name,  next,  previous,  up
@subsection XTLA
@cindex XTLA
@cindex @file{planner-xtla.el}, using

This module allows you to refer to changesets in Tom Lord's Arch (tla)
version control system. You can load the module with @code{(require
'planner-xtla)}. When you load the module, you can create tasks from
XTLA windows by positioning point on a revision.

XTLA URLs are of the form
@samp{xtla://miles@@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-19}

@file{planner-xtla.el} does not define any interactive functions.

@node Gnats,  , XTLA, Tracking Development
@comment  node-name,  next,  previous,  up
@subsection Gnats

@cindex Gnats
@cindex @file{planner-gnats.el}, using
@cindex bug reports, tracking

@file{planner-gnats.el} provides support for the GNU problem report
management system Gnats. This module allows you to refer to problem
reports using hyperlinks.

Configure your Emacs for Gnats access, then add @samp{(require
'planner-gnats)} to your @file{.emacs}. You can then create tasks from
Gnats edit or view buffers.

To add keybindings to Gnats, use @samp{(planner-gnats-insinuate)}.

Gnats URLs are of the form @samp{gnats:pr-number}.

@file{planner-gnats.el} does not define any interactive functions.

@node Advanced Configuration, Reference Material, Managing Your Information, Top
@comment  node-name,  next,  previous,  up
@chapter Advanced Configuration
@cindex configuration, advanced

@menu
* Customizing Your Day Pages::  Change your templates
* Variables to Customize::      Change various aspects of Planner behavior
* Ideas for Other Keybindings::  Add to and change the default keybindings
@end menu

@node Customizing Your Day Pages, Variables to Customize, Advanced Configuration, Advanced Configuration
@comment  node-name,  next,  previous,  up
@section Customizing Your Day Pages

With the variable @code{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 @ref{Diary}.

You can add interactive Lisp buttons with the @file{planner-lisp.el}
module. (@pxref{Interactive Lisp})

Your @code{planner-day-page-template} can also include @samp{|<lisp>|}
tags.

For more complex day pages, you can set
@code{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.

@node Variables to Customize, Ideas for Other Keybindings, Customizing Your Day Pages, Advanced Configuration
@comment  node-name,  next,  previous,  up
@section Variables to Customize
@cindex customize, variables to
@cindex variables, customization of
@cindex configuration, advanced, variables

If you want to change @code{planner-directory} and some other
variables, either use Customize (@kbd{M-x customize-group RET planner
RET}) or use @code{setq}.  An example of the latter follows.

@example
(setq planner-directory "~/Plans")
@end example

Other user options are:

@vindex planner-use-day-pages
@defopt 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, if using
@file{remember-planner}).
@end defopt

@vindex planner-use-plan-pages
@defopt planner-use-plan-pages
If you really don't like plan pages, you can set this variable to nil
and you won't be prompted for plan pages for tasks (and notes, if
using @file{remember-planner}).
@end defopt

@vindex planner-mode-hook
@defopt planner-mode-hook
List of functions to run after @code{planner-mode} is initialized.
@end defopt

@vindex planner-tasks-file-behavior
@defopt 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 @samp{save} means save but do not close buffers, and a
value of @samp{nil} means do not save any of the buffers.
@end defopt

@vindex planner-add-task-at-end-flag
@defopt 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.
@end defopt

@vindex planner-default-page
@defopt 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.
@end defopt

@vindex planner-hide-task-status-when-highlighting
@defopt 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.
@end defopt

@vindex planner-create-task-hook
@defopt planner-create-task-hook
Functions run after creating a task. @code{planner-id} hooks into
this.
@end defopt

@vindex planner-expand-name-favor-future-p
@defopt planner-expand-name-favor-future-p
If non-nil, partial dates (ex: @kbd{2} or @kbd{5.2}) are completed to
dates in the future instead of using the current year and month.
@end defopt

@vindex planner-task-dates-favor-future-p
@defopt planner-task-dates-favor-future-p
Like @code{planner-expand-name-favor-future-p}, but only for tasks.
@end defopt

@vindex planner-publish-dates-first-p
@defopt planner-publish-dates-first-p
Non-nil means list day pages first in the planner index.
@end defopt

@node Ideas for Other Keybindings,  , Variables to Customize, Advanced Configuration
@comment  node-name,  next,  previous,  up
@section Ideas for Other Keybindings
@cindex keybindings, customization of
@cindex configuration, advanced, keybindings
@cindex customize, keybindings to

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

@itemize @bullet

@item
@code{planner-copy-or-move-region}

@item
@code{planner-delete-task}

@item
@code{planner-task-delegated}

@item
@code{planner-task-pending}

@item
@code{planner-task-open}

@item
@code{planner-renumber-tasks}

@end itemize

You may find it easier to install keybindings for those operations by
inserting the following in your @file{.emacs} (or @file{_emacs}).
Note: This changes some of the default keybindings for Planner.

@example
(planner-install-extra-task-keybindings)
@end example

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

@itemize @bullet

@item
@kbd{C-c C-t} will be unbound from the default and will serve as the
prefix for the other task keybindings.

@item
@kbd{C-c C-t C-t}: @code{planner-create-task-from-buffer}.

@item
@kbd{C-c C-t C-k}: @code{planner-delete-task}.

@item
@kbd{C-c C-t C-u}: @code{planner-update-task}.

@item
@kbd{C-c C-t C-c}: @code{planner-copy-or-move-task}.

@item
@kbd{C-c C-t C-S-c}: @code{planner-copy-or-move-region}.

@item
@kbd{C-c C-t C-x}: @code{planner-task-done}.

@item
@kbd{C-c C-t C-S-x}: @code{planner-task-cancelled}.

@item
@kbd{C-c C-t C-d}: @code{planner-task-delegated}.

@item
@kbd{C-c C-t C-p}: @code{planner-task-pending}.

@item
@kbd{C-c C-t C-o}: @code{planner-task-in-progress}.

@item
@kbd{C-c C-t C-r}: @code{planner-raise-task}.

@item
@kbd{C-c C-t C-l}: @code{planner-lower-task}.

@item
@kbd{C-c C-t C-n}: @code{planner-renumber-tasks}.

@end itemize

Other keybindings can be configured by adding this to your
@file{.emacs} (or @file{_emacs}):

@example
(planner-install-extra-context-keybindings)
@end example

This will set up the following keybindings:

@itemize @bullet

@item
@kbd{shift up} @code{planner-move-up}

@item
@kbd{shift down} @code{planner-move-down}

@item
@kbd{shift right} @code{planner-jump-to-link}

@end itemize

@node Reference Material, Getting Help, Advanced Configuration, Top
@comment  node-name,  next,  previous,  up
@chapter Reference Material

@menu
* Keeping Track of Time::       
* Other Interactive Functions::  
* Planner Keybindings::         Default keybindings for Planner
* Sample Configuration Files::  
@end menu

@node Keeping Track of Time, Other Interactive Functions, Reference Material, Reference Material
@section Keeping Track of Time

One of the coolest things you can do with Planner is keep track of how
much time you spend not only on projects but even on particular tasks.
@file{planner-timeclock.el} makes it as easy and natural as marking a
task as in progress, postponed, or done. This can help you determine
just how much time you spend working each day. If you add estimates to
your task descriptions, you'll also be able to use this information to
improve your time estimation skills.

Here's how you can keep track of the time you


Then the fun began. I wanted to see if I could match my estimates.
Before I started working on a task, I used @kbd{C-c TAB} to mark it
@code{in progress} and start the clock. If I decided to work on
something else, I used @kbd{C-c TAB} to clock out of the previous task
and clock into the new one.

When I finished it, I used @kbd{C-c C-x} (@code{planner-task-done}) to
mark it completed and automatically clock out. This is not yet done
for cancelled tasks, so I clocked out of those manually with @kbd{C-c
C-o} (@code{timeclock-out}). I also clocked out whenever I caught
myself being distracted so that the totals wouldn't include the time I
spent chatting on #emacs or checking out del.icio.us links. =) At the
end of the day, I used
@code{planner-timeclock-summary-show-range-filter} to show me the time
elapsed for all of the tasks I'd worked on over the past two days.
Here's the report for that project, edited to reflect how it looks on
my screen and annotated with comments:

@example
Timeclock summary report for 2004.12.28 - 2004.12.29

Project     |     Time| Ratio| Task
JapanProject|  0:23:17|  3.6%| Translate javadoc comment for Messages.java
            |  0:33:48|  5.3%| Translate javadoc comment for LoginAction.java
            |  1:54:07| 17.8%| Study Struts in Japanese
            |  0:46:08|  7.2%| Add javadoc tags for input, output and forwards
            |  1:03:48|  9.9%| Help review code
            |  0:04:14|  0.7%| Import todo list
            |  0:00:37|  0.1%| 2min       Fix Menu Action's unnecessary code - delegated
            |  0:01:01|  0.2%| 2min       Remove unnecessary list in UserRemoveSetupAction - cancelled
            |  0:02:10|  0.3%| 2min       Remove hard-coded database path from MenuAction
            |  0:02:46|  0.4%| 30min      Create a superclass for our action classes that handles initialization of database and handling of privileges - remove all privilege handling in logic classes. ...
            |  0:07:32|  1.2%| 5min       Add a method that returns the validity of a user in MUserPeer.
            |  0:08:28|  1.3%| 5min       Fix indentation
            |  0:03:52|  0.6%| 10min      Fix UserPeer so that it doesn't get null pointer exceptions
            |  0:04:34|  0.7%| 5min       Add current password field in user_modify page
            |  0:21:56|  3.4%| 15min      Make a super class for our service classes that will receive the database connection. (cancelled)
            |  0:06:05|  0.9%| 10min      Remove hard-coded constants from the Logic classes
            |  0:10:55|  1.7%| 10min      Move logic from UserBean.checkPassword to UserListLogic
            |  0:01:20|  0.2%| 20min      Guard against null pointer exceptions in peer classes
            |  0:04:57|  0.8%| 10min      Instead of displaying uneditable data with bean:write, just disable the html:text element
            |  0:25:03|  3.9%| 10min      Deploy 10:00 version
            |  0:04:46|  0.7%| 5min       Separate the configuration file of database and system into another uninternationalized property file.
            |  2:09:48| 20.2%| 1h         Decide on a naming convention for localized messages and update files
            |  0:00:07|  0.0%| 20min      Explain what is happening in UserModifyAction's nested ifs - pending
            |  1:50:23| 17.2%| 2h         Write Javadoc comments in English and Japanese to explain bean structure
            |  0:04:19|  0.7%| 2h         Write Javadoc comments in English and Japanese to explain peer operations (pending)
            |  0:05:40|  0.9%| 20min      Make a factory class for the database - pending
     Total: | 10:41:41|100.0%|      

Day began: 13:03:58, Day ended: 20:51:46
Time elapsed: 31:47:48, Time clocked: 10:41:41
Time clocked ratio: 33.6%
@end example

The time record isn't perfect. I cancelled some tasks after thinking
about them a little and did some tasks simultaneously. Sometimes I
didn't notice that I was getting distracted, too. Still, having all of
that time information neatly summarized made me realize a number of
things.

First, I goof off much less when I have a nice, broken-down task list
in front of me. There's just something about knowing there's a five-
or ten-minute hack you can get out of the way. I found myself looking
forward to getting to the next task just to see if I could make my
estimate. That said, seeing a five-minute task stretch and stretch due
to unforeseen problems did make me a little nervous. I should probably
just make generous estimates so that I don't end up with bugs because
of haste.

Second, I don't goof off as much as I thought I did, although there's
still room for improvement. Yesterday's workday was 9:00 - 12:00, 1:00
- 5:30--7.5 hours. Today was the last day of work, so cleaning and
celebration interrupted my hacking at around 3:00--5 hours of work.
According to my task list, 10:41/12:30 was productive work. Hmm. 1:49
hours unclocked time when I was thinking or goofing off.
planner-timeclock-summary-show for today reveals that I actually
clocked 5:30 today, which means the goofing off happened yesterday.
That makes sense; I remember a pretty long unclocked segment
recuperating from Japanese overload. (This was before we came up with
the task list.)

Third, keeping track of time is way, way cool even if you don't bill
anyone for your time.

Like the idea? It's easy to try out. Just add

@example
(require 'planner-timeclock)
(require 'planner-timeclock-summary)
@end example

to your ~/.emacs. If you want to try it out now, eval those statements
in your Emacs session. After that, simply use @kbd{C-c TAB} to ``clock
in'' a task before you start working on it and @kbd{C-c C-x}
(@code{planner-task-done}) to mark it completed. @kbd{M-x
planner-task-pending} also clocks out the current task if it was
clocked in. To see a summary of how you spent your day, check out the
different functions in @file{planner-timeclock-summary}.

See @ref{Timeclock} for more details.

Happy hacking!

@node Other Interactive Functions, Planner Keybindings, Keeping Track of Time, Reference Material
@comment  node-name,  next,  previous,  up
@section Other Interactive Functions

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

For a list of Planner keybindings, see @ref{Planner Keybindings}.

They are listed in no particular order.

@file{planner.el} defines the following interactive functions:


@defun 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
@var{planner-default-task-priority} and call @code{planner-create-task}
or @code{planner-create-task-from-buffer}.
@end defun

@defun 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
@var{planner-default-task-priority} and call @code{planner-create-task}
or @code{planner-create-task-from-buffer}.
@end defun

@defun 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
@var{planner-default-task-priority} and call @code{planner-create-task} or
@code{planner-create-task-from-buffer}.
@end defun

@defun planner-install-extra-context-keybindings
Install extra context-sensitive keybindings. These keybindings
conflict with @file{windmove.el}, but might be useful.
@end defun

@defun planner-narrow-to-section section &optional create
Widen to the whole page and narrow to the section labelled
@var{section}.  If @var{create} is non-nil and the section is not found,
the section is created.  Return non-nil if @var{section} was found or
created.
@end defun

@defun planner-save-buffers
Save all planner-mode buffers.
@end defun

@defun planner-seek-to-first section
Positions the point at the specified @var{section}, or @samp{Tasks} if
not specified.
@end defun

@defun planner-save-buffers
Save all planner buffers.
@end defun

@defun planner-calendar-insinuate
This hooks Planner into  Emacs Calendar (@pxref{Calendar/Diary, ,
, Emacs, GNU Emacs Manual}).

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

@table @kbd

@item  n
Jump to the planner page for the current day.

@item  N
Display the planner page for the current day.
@end table

@end defun

@defun planner-kill-calendar-files
Remove planner files shown from Calendar (@pxref{Calendar/Diary, , ,
Emacs, GNU Emacs Manual}).

@end defun

@defun planner-calendar-goto
Goto the plan page corresponding to the calendar date
(@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
@end defun

@defun planner-calendar-show
Show the plan page for the calendar date under point in another window
(@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
@end defun

@defun planner-calendar-select
Return to @code{planner-read-date} with the date currently selected
(@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
@end defun

@defun planner-jump-to-link
Jump to the item linked to by the current item.
@end defun

@defun planner-move-up
Move a task up. You can use this to indicate that you will do a task
before another one. On a note, go to the previous note. On a headline,
go to the previous headline of the same depth.
@end defun

@defun planner-move-down 
Move down. You can use this to indicate that you will do a task after
another one. On a note, go to the next note. On a headline, go to the
next headline of the same depth.
@end defun

@node Planner Keybindings, Sample Configuration Files, Other Interactive Functions, Reference Material
@comment  node-name,  next,  previous,  up
@section Planner Keybindings
@cindex keybindings, list

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

Here is a summary of the keystrokes available:

@table @kbd

@item 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.

@item C-c C-u
Move a task up.

@item C-c C-d
Move a task down.

@item C-c C-s
Mark the task as in progress or delegated.

@item C-c C-x
Mark the task as finished.

@item 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.

@item 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.

@item C-c C-n
Jump to today's task page.  If you call
@code{(planner-calendar-insinuate)}, typing @kbd{n} in the Emacs
calendar (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) will jump
to today's task page.

@item C-c C-x
@code{planner-task-done}

@item C-c C-z
@code{planner-task-in-progress}

@item C-c C-d
@code{planner-lower-task}

@item C-c C-u
@code{planner-raise-task}

@item C-c C-c
@code{planner-copy-or-move-task}

@item C-c C-t
@code{planner-create-task-from-buffer}

@item C-c C-j
This is a prefix command.

@item C-c C-n
@code{planner-goto-today}

@item C-c C-j C-r
@code{planner-goto-most-recent}

@item C-c C-j C-t
@code{planner-goto-tomorrow}

@item C-c C-j C-y
@code{planner-goto-yesterday}

@item C-c C-j C-j
@code{planner-goto-today}

@item C-c C-j C-n
@code{planner-goto-next-daily-page}

@item C-c C-j C-p
@code{planner-goto-previous-daily-page}

@item C-c C-j C-d
@code{planner-goto}

@end table

@node Sample Configuration Files,  , Planner Keybindings, Reference Material
@comment  node-name,  next,  previous,  up
@section Sample Configuration Files
@cindex configuration, sample

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

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 to our mailing
list (@pxref{Getting Help}).  We look forward to helping you customizing
planner to fit your needs.

@menu
* File Organization::           
* Bare-Bones Planning::         
* Bare-Bones Planning with Plan Pages::  
* Tasks on Plan Pages with Some Day Pages::  
* Hierarchical Tasks::          
@end menu

@node File Organization, Bare-Bones Planning, Sample Configuration Files, Sample Configuration Files
@subsection File Organization

@itemize
@item @strong{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 @kbd{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.

@item @strong{Cross-referenced with plan pages.}

You can associate your tasks with projects either when you create the
task or later, with @kbd{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.

@item @strong{Just plan pages.}

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

@end itemize

@node Bare-Bones Planning, Bare-Bones Planning with Plan Pages, File Organization, Sample Configuration Files
@subsection 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
@code{planner-use-day-pages} variable to nil before loading planner.
For example, you can put this in your @file{~/.emacs} (or @file{_emacs}):

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

When you create a task or note, planner will not prompt you for a
date.  If you press @key{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 @command{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.

@node Bare-Bones Planning with Plan Pages, Tasks on Plan Pages with Some Day Pages, Bare-Bones Planning, Sample Configuration Files
@subsection 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 @command{planner-create-task-from-buffer} command
prompts you for a plan page when you create a task.



@node Tasks on Plan Pages with Some Day Pages, Hierarchical Tasks, Bare-Bones Planning with Plan Pages, Sample Configuration Files
@subsection 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.

@example
(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)))
@end example

@node Hierarchical Tasks,  , Tasks on Plan Pages with Some Day Pages, Sample Configuration Files
@subsection Hierarchical Tasks
@cindex hierarchical tasks
@cindex tasks, hierarchy of

You can use @file{allout.el} or other modes for outlining to support
hierarchical tasks in plan pages. No special support is needed.

Tasks created by @command{planner-create-task-from-buffer} and
@code{planner-create-task} are created in the @samp{* Tasks} section.
If @code{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 @file{LearnPlanner} plan page might contain the
following lines:

@example
* Learn how to use planner.el

** Installation

#C0 _ Decide where to put Planner
#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

...
@end example

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


@node Getting Help, Acknowledgements, Reference Material, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Help
@cindex help, getting
@cindex bugs, reporting

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

Planner has an official website at
@url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}.  It is a
collaborative wiki.

Bugs may be reported using the Planner Bug-Tracker at
@url{http://gna.org/bugs/?group=planner-el}.

Planner has three mailing lists.

@table @samp

@item planner-el-announce
Low-traffic list for planner-related announcements.

You can join this mailing list (@email{planner-el-announce@@gna.org})
using the subscription form at
@url{http://mail.gna.org/listinfo/planner-el-announce/}.  This
mailing list is also available via Gmane (@url{http://gmane.org/}). The
group is called @samp{gmane.emacs.planner.announce}.

@item planner-el-discuss
Discussion, bugfixes, suggestions, tips, and the like for Planner.
This mailing list also includes the content of planner-el-announce.

You can join this mailing list (@email{planner-el-discuss@@gna.org})
using the subscription form at
@url{http://mail.gna.org/listinfo/planner-el-discuss/}.  This mailing
list is also available via Gmane with the identifier
@samp{gmane.emacs.planner.general}.

@item planner-el-logs
Log messages for commits made to Planner.

You can join this mailing list (@email{planner-el-logs@@gna.org}) using
the subscription form at
@url{http://mail.gna.org/listinfo/planner-el-logs/}.  This mailing list
is also available via Gmane with the identifier
@samp{gmane.emacs.planner.scm}.

@item planner-el-cvs
Generated bug reports for Planner.

You can join this mailing list (@email{planner-el-cvs@@gna.org}) using
the subscription form at
@url{http://mail.gna.org/listinfo/planner-el-cvs/}.  This mailing list
is also available via Gmane with the identifier
@samp{gmane.emacs.planner.cvs}.

@end table

You can also contact the maintainer of Planner, John Sullivan, at
@email{john@@wjsullivan.net}, but it is better to use the other options.

You can explore the relevant sections of the EmacsWiki.org:

@itemize @bullet

@item
@url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}

@item
@url{http://www.emacswiki.org/cgi-bin/wiki/MuseMode}

@item
@url{http://www.emacswiki.org/cgi-bin/wiki/RememberMode}

@end itemize

You can visit the IRC Freenode channel @samp{#emacs}. Many of the
contributors are frequently around and willing to answer your
questions.

There is an Orkut community called PlannerMode.

For issues relating to this documentation, please contact John
Sullivan at @email{john@@wjsullivan.net}.

@node Acknowledgements, GNU General Public License, Getting Help, Top
@comment  node-name,  next,  previous,  up
@chapter Acknowledgements
@itemize
@item Maintainers

@cindex maintainers

@itemize
@item 2006

John Sullivan volunteered to maintain Planner, and Michael Olson passed
the maintainership on to him with the release of Planner 3.41.

@item 2005

Michael Olson, Sacha Chua, and several others from the Planner community
ported Planner to use Muse instead of emacs-wiki.  Michael Olson became
the maintainer of Planner.

@item 2004

Damien Elmes handed EmacsWikiMode to Mark Triggs for a short period of
time.  Mark Triggs deferred to Sacha Chua as official maintainer of
Planner.  Sacha Chua volunteered to maintain RememberMode.
Michael Olson became the maintainer of both emacs-wiki and Muse.

@item 2003

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

@item 2001

John Wiegley wrote EmacsWikiMode and Planner.
@end itemize

@item Contributors
@cindex contributors

For a complete list of people who have helped out with Planner, please
check out the @file{AUTHORS} file that is included with Planner.

@end itemize

@node GNU General Public License, Concept Index, Acknowledgements, Top
@comment  node-name,  next,  previous,  up
@appendix GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991
@cindex GPL
@cindex GNU General Public License

@c The GNU General Public License.
@center Version 3, 29 June 2007

@c This file is intended to be included within another document,
@c hence no sectioning command or @node.  

@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}

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

@heading Preamble

The GNU General Public License is a free, copyleft license for
software and other kinds of works.

The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom
to share and change all versions of a program---to make sure it remains
free software for all its users.  We, the Free Software Foundation,
use the GNU General Public License for most of our software; it
applies also to any other work released this way by its authors.  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
them 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 prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you
have certain responsibilities if you distribute copies of the
software, or if you modify it: responsibilities to respect the freedom
of others.

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  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.

Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software.  For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so.  This is fundamentally incompatible with the
aim of protecting users' freedom to change the software.  The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products.  If such problems arise substantially in
other domains, we stand ready to extend this provision to those
domains in future versions of the GPL, as needed to protect the
freedom of users.

Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish
to avoid the special danger that patents applied to a free program
could make it effectively proprietary.  To prevent this, the GPL
assures that patents cannot be used to render the program non-free.

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

@heading TERMS AND CONDITIONS

@enumerate 0
@item Definitions.

``This License'' refers to version 3 of the GNU General Public License.

``Copyright'' also means copyright-like laws that apply to other kinds
of works, such as semiconductor masks.

``The Program'' refers to any copyrightable work licensed under this
License.  Each licensee is addressed as ``you''.  ``Licensees'' and
``recipients'' may be individuals or organizations.

To ``modify'' a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of
an exact copy.  The resulting work is called a ``modified version'' of
the earlier work or a work ``based on'' the earlier work.

A ``covered work'' means either the unmodified Program or a work based
on the Program.

To ``propagate'' a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy.  Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.

To ``convey'' a work means any kind of propagation that enables other
parties to make or receive copies.  Mere interaction with a user
through a computer network, with no transfer of a copy, is not
conveying.

An interactive user interface displays ``Appropriate Legal Notices'' to
the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License.  If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.

@item Source Code.

The ``source code'' for a work means the preferred form of the work for
making modifications to it.  ``Object code'' means any non-source form
of a work.

A ``Standard Interface'' means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.

The ``System Libraries'' of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form.  A
``Major Component'', in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.

The ``Corresponding Source'' for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities.  However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work.  For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.

The Corresponding Source need not include anything that users can
regenerate automatically from other parts of the Corresponding Source.

The Corresponding Source for a work in source code form is that same
work.

@item Basic Permissions.

All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met.  This License explicitly affirms your unlimited
permission to run the unmodified Program.  The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work.  This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey,
without conditions so long as your license otherwise remains in force.
You may convey covered works to others for the sole purpose of having
them make modifications exclusively for you, or provide you with
facilities for running those works, provided that you comply with the
terms of this License in conveying all material for which you do not
control copyright.  Those thus making or running the covered works for
you must do so exclusively on your behalf, under your direction and
control, on terms that prohibit them from making any copies of your
copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the
conditions stated below.  Sublicensing is not allowed; section 10
makes it unnecessary.

@item Protecting Users' Legal Rights From Anti-Circumvention Law.

No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.

When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such
circumvention is effected by exercising rights under this License with
respect to the covered work, and you disclaim any intention to limit
operation or modification of the work as a means of enforcing, against
the work's users, your or third parties' legal rights to forbid
circumvention of technological measures.

@item Conveying Verbatim Copies.

You may convey 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;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.

@item Conveying Modified Source Versions.

You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these
conditions:

@enumerate a
@item 
The work must carry prominent notices stating that you modified it,
and giving a relevant date.

@item
The work must carry prominent notices stating that it is released
under this License and any conditions added under section 7.  This
requirement modifies the requirement in section 4 to ``keep intact all
notices''.

@item
You must license the entire work, as a whole, under this License to
anyone who comes into possession of a copy.  This License will
therefore apply, along with any applicable section 7 additional terms,
to the whole of the work, and all its parts, regardless of how they
are packaged.  This License gives no permission to license the work in
any other way, but it does not invalidate such permission if you have
separately received it.

@item
If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your work
need not make them do so.
@end enumerate

A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
``aggregate'' if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit.  Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.

@item  Conveying Non-Source Forms.

You may convey a covered work in object code form under the terms of
sections 4 and 5, provided that you also convey the machine-readable
Corresponding Source under the terms of this License, in one of these
ways:

@enumerate a
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium customarily
used for software interchange.

@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a written
offer, valid for at least three years and valid for as long as you
offer spare parts or customer support for that product model, to give
anyone who possesses the object code either (1) a copy of the
Corresponding Source for all the software in the product that is
covered by this License, on a durable physical medium customarily used
for software interchange, for a price no more than your reasonable
cost of physically performing this conveying of source, or (2) access
to copy the Corresponding Source from a network server at no charge.

@item
Convey individual copies of the object code with a copy of the written
offer to provide the Corresponding Source.  This alternative is
allowed only occasionally and noncommercially, and only if you
received the object code with such an offer, in accord with subsection
6b.

@item
Convey the object code by offering access from a designated place
(gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge.  You need not require recipients to copy the
Corresponding Source along with the object code.  If the place to copy
the object code is a network server, the Corresponding Source may be
on a different server (operated by you or a third party) that supports
equivalent copying facilities, provided you maintain clear directions
next to the object code saying where to find the Corresponding Source.
Regardless of what server hosts the Corresponding Source, you remain
obligated to ensure that it is available for as long as needed to
satisfy these requirements.

@item
Convey the object code using peer-to-peer transmission, provided you
inform other peers where the object code and Corresponding Source of
the work are being offered to the general public at no charge under
subsection 6d.

@end enumerate

A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.

A ``User Product'' is either (1) a ``consumer product'', which means any
tangible personal property which is normally used for personal,
family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling.  In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of
coverage.  For a particular product received by a particular user,
``normally used'' refers to a typical or common use of that class of
product, regardless of the status of the particular user or of the way
in which the particular user actually uses, or expects or is expected
to use, the product.  A product is a consumer product regardless of
whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant
mode of use of the product.

``Installation Information'' for a User Product means any methods,
procedures, authorization keys, or other information required to
install and execute modified versions of a covered work in that User
Product from a modified version of its Corresponding Source.  The
information must suffice to ensure that the continued functioning of
the modified object code is in no case prevented or interfered with
solely because modification has been made.

If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information.  But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).

The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or
updates for a work that has been modified or installed by the
recipient, or for the User Product in which it has been modified or
installed.  Access to a network may be denied when the modification
itself materially and adversely affects the operation of the network
or violates the rules and protocols for communication across the
network.

Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.

@item Additional Terms.

``Additional permissions'' are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law.  If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.

When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it.  (Additional permissions may be written to require their own
removal in certain cases when you modify the work.)  You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders
of that material) supplement the terms of this License with terms:

@enumerate a
@item
Disclaiming warranty or limiting liability differently from the terms
of sections 15 and 16 of this License; or

@item
Requiring preservation of specified reasonable legal notices or author
attributions in that material or in the Appropriate Legal Notices
displayed by works containing it; or

@item
Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or

@item
Limiting the use for publicity purposes of names of licensors or
authors of the material; or

@item
Declining to grant rights under trademark law for use of some trade
names, trademarks, or service marks; or

@item
Requiring indemnification of licensors and authors of that material by
anyone who conveys the material (or modified versions of it) with
contractual assumptions of liability to the recipient, for any
liability that these contractual assumptions directly impose on those
licensors and authors.
@end enumerate

All other non-permissive additional terms are considered ``further
restrictions'' within the meaning of section 10.  If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term.  If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions; the
above requirements apply either way.

@item Termination.

You may not propagate or modify a covered work except as expressly
provided under this License.  Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).

However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.

Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.

@item Acceptance Not Required for Having Copies.

You are not required to accept this License in order to receive or run
a copy of the Program.  Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance.  However,
nothing other than this License grants you permission to propagate or
modify any covered work.  These actions infringe copyright if you do
not accept this License.  Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.

@item Automatic Licensing of Downstream Recipients.

Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License.  You are not responsible
for enforcing compliance by third parties with this License.

An ``entity transaction'' is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations.  If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License.  For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.

@item Patents.

A ``contributor'' is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based.  The
work thus licensed is called the contributor's ``contributor version''.

A contributor's ``essential patent claims'' are all patent claims owned
or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version.  For
purposes of this definition, ``control'' includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.

In the following three paragraphs, a ``patent license'' is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement).  To ``grant'' such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.

If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients.  ``Knowingly relying'' means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.

A patent license is ``discriminatory'' if it does not include within the
scope of its coverage, prohibits the exercise of, or is conditioned on
the non-exercise of one or more of the rights that are specifically
granted under this License.  You may not convey a covered work if you
are a party to an arrangement with a third party that is in the
business of distributing software, under which you make payment to the
third party based on the extent of your activity of conveying the
work, and under which the third party grants, to any of the parties
who would receive the covered work from you, a discriminatory patent
license (a) in connection with copies of the covered work conveyed by
you (or copies made from those copies), or (b) primarily for and in
connection with specific products or compilations that contain the
covered work, unless you entered into that arrangement, or that patent
license was granted, prior to 28 March 2007.

Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.

@item No Surrender of Others' Freedom.

If 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 convey
a covered work so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a
consequence you may not convey it at all.  For example, if you agree
to terms that obligate you to collect a royalty for further conveying
from those to whom you convey the Program, the only way you could
satisfy both those terms and this License would be to refrain entirely
from conveying the Program.

@item Use with the GNU Affero General Public License.

Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work.  The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.

@item Revised Versions of this License.

The Free Software Foundation may publish revised and/or new versions
of the GNU 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 that a certain numbered version of the GNU General Public
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that numbered version or
of any later version published by the Free Software Foundation.  If
the Program does not specify a version number of the GNU General
Public License, you may choose any version ever published by the Free
Software Foundation.

If the Program specifies that a proxy can decide which future versions
of the GNU General Public License can be used, that proxy's public
statement of acceptance of a version permanently authorizes you to
choose that version for the Program.

Later license versions may give you additional or different
permissions.  However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.

@item Disclaimer of Warranty.

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.

@item Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
CONVEYS 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.

@item Interpretation of Sections 15 and 16.

If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.

@end enumerate

@heading END OF TERMS AND CONDITIONS

@heading 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
state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and a brief idea of what it does.}  
Copyright (C) @var{year} @var{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 3 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, see @url{http://www.gnu.org/licenses/}.
@end smallexample

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

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

@smallexample
@var{program} Copyright (C) @var{year} @var{name of author} 
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, your
program's commands might be different; for a GUI interface, you would
use an ``about box''.

You should also get your employer (if you work as a programmer) or school,
if any, to sign a ``copyright disclaimer'' for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
@url{http://www.gnu.org/licenses/}.

The GNU 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 Lesser General Public License instead of this License.  But
first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.

@node Concept Index,  , GNU General Public License, Top
@comment  node-name,  next,  previous,  up
@unnumbered Index

@printindex cp

@bye