1 \input texinfo @c -*-texinfo-*-
3 @setfilename planner-el.info
9 * planner-el: (planner-el). planner.el: Day planner/organizer for Emacs.
15 This manual is for Planner version 3.41.
17 Copyright @copyright{} 2001, 2004, 2005, 2006 Free Software Foundation, Inc.@*
18 Parts copyright @copyright{} 2005 Jim Ottaway@*
19 Parts copyright @copyright{} 2005 Dryice Dong Liu
22 Permission is granted to copy, distribute and/or modify this document
23 under the terms of the GNU General Public License, Version 2.0
24 or any later version published by the Free Software Foundation.
25 A copy of the license is included in the section entitled ``GNU
26 General Public License.''
31 @title Guide to Planner
32 @subtitle a day planner and organizer
33 @subtitle for GNU Emacs and XEmacs
35 @c The following two commands
36 @c start the copyright page.
38 @vskip 0pt plus 1filll
42 @c So the toc is printed at the start
46 @node Top, Preface, (dir), (dir)
47 @comment node-name, next, previous, up
57 * Overview:: A discussion of different approaches to planning
59 * More about Planner:: In-depth look at some core features
60 * Managing Your Information:: Integration with external programs
61 * Advanced Configuration::
62 * Reference Material::
65 * GNU General Public License::
69 --- The Detailed Node Listing ---
74 * Creating Your Planner::
76 * Advanced Installation::
80 * Installing from a Source Archive::
81 * Installing from Arch::
82 * Installing from Debian::
86 * Planning based on the Franklin-Covey Approach::
103 * Making Files Pretty::
105 * Interactive Lisp:: planner-lisp.el
106 * Publishing:: planner-publish.el
107 * Experimental Functions:: planner-experimental.el
111 * Creating New Tasks::
112 * Organizing Your Tasks::
113 * Task Reports and Overviews::
119 * Task IDs:: planner-id.el
120 * Cyclic Tasks:: planner-cyclic.el
122 * Deadlines:: planner-deadline.el
124 Organizing Your Tasks
126 * Multiple Projects::
129 * Carrying Over Unfinished Tasks::
131 * Task Ranks:: planner-rank.el
132 * Grouping Tasks:: planner-trunk.el
134 Task Reports and Overviews
136 * Accomplishments:: planner-accomplishments.el
137 * Status Reports:: planner-report.el
138 * Task Overviews:: planner-tasks-overview.el
140 * planner-registry:: Keep track of annotations
141 * planner-zoom:: View and navigate tasks by time period
145 * Using Allout Mode:: Quickly navigating your notes
146 * <notes>:: Note headlines
147 * <past-notes>:: Index of past notes
148 * Note Indices:: planner-notes-index.el
152 * Publishing Planner pages:: planner-publish.el
153 * Publishing Calendars:: planner-calendar.el
154 * Authz Access Restriction:: planner-authz.el
155 * RSS Publication:: Sharing notes with planner-rss.el
156 * iCal Task Publication:: Sharing tasks with planner-ical.el
157 * RDF Publication:: planner-rdf.el
161 * Publishing with planner-rdf::
163 * planner-rdf Usage Examples::
165 Managing Your Information
167 * E-mail:: Linking notes and tasks to messages
168 * Scheduling and Time:: Tracking appointments and where your time goes
169 * Finances:: Display your account balances and more
170 * Contacts and Conversations:: BBDB and ERC
171 * Tracking Research and Resources:: The Web, bibliographies, and bookmarks
172 * Tracking Development::
176 * Unix mail:: Unix mailboxes: planner-unix-mail.el
177 * Gnus:: Gnus mail and news reader: planner-gnus.el
178 * VM:: VM mail reader: planner-vm.el
179 * Wanderlust:: Wanderlust mail reader: planner-wl.el
180 * MH-E:: MH-E mail reader: planner-mhe.el
181 * Rmail:: Rmail: planner-rmail.el
185 * Diary:: Using the Emacs diary: planner-diary.el
186 * Appointments:: Appointments in plan pages: planner-appt.el
187 * Timeclock:: Time tracking: planner-timeclock.el
188 * schedule.el:: Project completion: planner-schedule.el
192 * Planner-Diary Advanced Features::
196 * Task-based Appointments::
197 * Schedule-based Appointments::
198 * Viewing Appointments::
199 * Appointment Updating on Save::
200 * Appointment and Calendar Integration::
201 * Appointment Hooks::
205 * Ledger:: Personal finances: planner-ledger.el
207 Contacts and Conversations
209 * BBDB:: Contacts: planner-bbdb.el
210 * Emacs Relay Chat:: Internet Relay Chat: planner-erc.el
212 Tracking Research and Resources
214 * W3m:: Web browser: planner-w3m.el
215 * BibTeX:: Bibliographies: planner-bibtex.el
216 * Bookmark:: Bookmarks: planner-bookmark.el
220 * Log Edit:: Changelogs: planner-log-edit.el
221 * PSVN:: svn changesets: planner-psvn.el
222 * XTLA:: TLA changesets: planner-xtla.el
223 * Gnats:: Gnats: The GNU bug reporting system
225 Advanced Configuration
227 * Customizing Your Day Pages:: Change your templates
228 * Variables to Customize:: Change various aspects of Planner behavior
229 * Ideas for Other Keybindings:: Add to and change the default keybindings
233 * Keeping Track of Time::
234 * Other Interactive Functions::
235 * Planner Keybindings:: Default keybindings for Planner
236 * Sample Configuration Files::
238 Sample Configuration Files
240 * File Organization::
241 * Bare-Bones Planning::
242 * Bare-Bones Planning with Plan Pages::
243 * Tasks on Plan Pages with Some Day Pages::
244 * Hierarchical Tasks::
249 @node Preface, Introduction, Top, Top
250 @comment node-name, next, previous, up
253 This document describes Planner, which was written by John Wiegley and
254 is now maintained by John Sullivan (@pxref{Acknowledgements}).
256 This document is a work in progress, and your contribution will be
257 greatly appreciated. Please e-mail comments and suggestions to the
258 mailing list (@pxref{Getting Help}). In the subject line of your
259 e-mail, include the word @samp{Planner}.
261 This documentation is available in eye-pleasing formats including PDF
262 and HTML at @url{http://www.mwolson.org/static/doc/}.
264 Documentation author and maintainer: John Sullivan
265 @email{john@@wjsullivan.net}
268 John Sullivan (johnsu01)@*
271 @node Introduction, Installation, Preface, Top
272 @comment node-name, next, previous, up
273 @chapter Introduction
275 Planner is an organizer and day planner for Emacs. It helps you keep
276 track of your pending and completed tasks, daily schedule, dates to
277 remember, notes and inspirations. It is a powerful tool not only for
278 managing your time and productivity, but also for keeping within easy
279 keystroke reach all of the information you need to be productive. It can
280 even publish reports charting your work for your personal web page, your
281 conscience, or your soon-to-be-impressed boss.
283 In fact, because it uses as its building blocks simple plain-text files,
284 it is an incredibly modular and flexible tool capable of shaping and
285 handling your personal information in ways whose variety is limited only
286 by your imagination. Because of this, Planner has a very active and
287 generous community who regularly share their innovations with each
288 other. Many of these modules and extensions are included in the archive
289 that you will download. Once you get the basics down, you'll probably
290 want to explore some of them. But as you read this manual and work with
291 Planner, keep in mind that the basic core is actually very simple, and
292 it might be worth spending time with just that before delving into the
295 Because they are plain text with very few requirements, the organizer
296 pages kept by Planner can be as basic or as detailed as you
297 like. Your pages can be simple to-do lists with no more additional
298 information than what you would scrawl on a napkin, or they can be a
299 highly technical affair involving hyperlinks, embedded Lisp code,
300 appointment schedules and RSS feeds. As with so much in Emacs, it's
303 To get started with Planner, you first need to download it, and possibly
304 also the packages it depends on (@pxref{Installation}).
306 @node Installation, Overview, Introduction, Top
307 @comment node-name, next, previous, up
308 @chapter Installation
311 Planner depends on Muse. Information for downloading and installing
313 @url{http://www.mwolson.org/static/doc/muse.html}.
315 Make sure that you use the latest Muse release. Development code might
319 * Getting the Files::
320 * Creating Your Planner::
322 * Advanced Installation::
325 @node Getting the Files, Creating Your Planner, Installation, Installation
326 @comment node-name, next, previous, up
327 @section Getting the Files
329 Currently, there are three ways to obtain and install Planner. You can
330 install it from a source archive, Arch repository, or Debian package.
333 * Installing from a Source Archive::
334 * Installing from Arch::
335 * Installing from Debian::
338 @node Installing from a Source Archive, Installing from Arch, Getting the Files, Getting the Files
339 @comment node-name, next, previous, up
340 @subsection Installing from a Source Archive
341 @cindex source code archive, installing from
343 You can install Planner from the source archive packaged and
344 distributed directly by the maintainer. This archive is provided in
345 both @file{.tar.gz} and @file{.zip} format. If you don't know where to
346 extract these archives, create a @file{~/elisp} directory, and extract
351 Download and unpack either
352 @url{http://www.mwolson.org/static/dist/planner-latest.tar.gz} or
353 @url{http://www.mwolson.org/static/dist/planner-latest.zip}.
357 @url{http://www.mwolson.org/static/dist/muse-latest.tar.gz} or
358 @url{http://www.mwolson.org/static/dist/muse-latest.zip}.
362 @url{http://www.mwolson.org/static/dist/remember-latest.tar.gz} or
363 @url{http://www.mwolson.org/static/dist/remember-latest.zip}.
365 @item Edit your @file{~/.emacs} (@file{_emacs} on Microsoft Windows).
367 Replace @file{/path/to} with wherever you extracted the files.
370 ;; Add the directories to your load path
371 (add-to-list 'load-path "/path/to/muse/lisp")
372 (add-to-list 'load-path "/path/to/planner")
373 (add-to-list 'load-path "/path/to/remember")
380 @subheading Updating Your Version
382 Download a new version and extract it over the old directory. Don't
383 forget to delete any byte-compiled files (@file{*.elc}) in the
384 directories (which can be accomplished by running ``make clean'') so
385 that the new code will be used.
387 @node Installing from Arch, Installing from Debian, Installing from a Source Archive, Getting the Files
388 @comment node-name, next, previous, up
389 @subsection Installing from Arch
390 @cindex Arch repositories
391 @cindex Arch, installing from
393 Arch allows you to retrieve previous versions and select specific
394 features and bugfixes. Debian users can install Arch with @kbd{apt-get
395 install tla}. Users of other distributions should see
396 @url{http://regexps.srparish.net/www/}.
398 To get started with Planner using Arch, you'll need to run some initial
399 commands to register your local copy of the archive and retrieve the
403 # Register the Muse archive
404 tla register-archive -f http://www.mwolson.org/archives/2006
406 # Register the Planner archive
407 tla register-archive -f http://arch.gna.org/planner-el/archive-2006
409 # Register the Remember archive
410 tla register-archive -f http://arch.gna.org/remember-el/archive
413 tla get mwolson@@gnu.org--2006/muse--main--1.0 muse
415 # Download planner module into the planner/ subdirectory
416 tla get mwolson@@gnu.org--2006-planner-el/planner-el--devel--0 planner
419 tla get remember-el@@arch.gna.org/remember--main--0 remember
423 Then add the following lines to your @code{~/.emacs}:
426 ;; Add the directories to your load path
427 (add-to-list 'load-path "/path/to/muse/lisp")
428 (add-to-list 'load-path "/path/to/planner")
429 (add-to-list 'load-path "/path/to/remember")
435 You can also browse Planner's Arch repository on the web at
436 @url{http://www.mwolson.org/cgi-bin/archzoom/archzoom.cgi/mwolson@@gnu.org--2006-planner-el}.
438 @subheading Updating Your Version
439 @cindex Arch, updating from
441 To stay up-to-date using Arch, here are some commands that might be
444 To list upstream changes not in local copy:
447 # Change to the source directory you are interested in. Example:
450 # Display the summary of changes
451 tla missing --summary
454 To update to the latest version:
458 cd ../planner; tla update
459 cd ../remember; tla update
462 Don't forget to delete any byte-compiled files (@file{*.elc}) in the
463 directories so that the new code will be used.
465 @node Installing from Debian, , Installing from Arch, Getting the Files
466 @comment node-name, next, previous, up
467 @subsection Installing from Debian
468 @cindex Debian package
470 Debian packages for Planner, Muse, and Remember are available in Debian
471 proper as the @code{planner-el}, @code{muse-el}, and @code{remember-el}
472 packages, respectively.
474 If you wish to try experimental packages, add the following lines to
475 your @file{/etc/apt/sources.list}
478 deb http://www.mwolson.org/debian/ ./
481 Then, do the following steps as root:
485 apt-get install muse-el
486 apt-get install planner-el
487 apt-get install remember-el
490 If you get some warning about the key not being trusted, you can either
491 ignore it or do the following.
494 gpg --keyserver pgpkeys.mit.edu --recv-key f3a8d319
495 gpg -a --export f3a8d319 | sudo apt-key add -
498 @subheading Updating Your Version
499 @cindex Debian package, updating
501 If you installed Planner from Debian, do @kbd{apt-get update; apt-get
502 upgrade} to upgrade all packages that can be upgraded, or @kbd{apt-get
503 update; apt-get install planner-el} to upgrade just planner-el.
505 @node Creating Your Planner, Components, Getting the Files, Installation
506 @section Creating Your Planner
508 Now that you have installed the files for Planner and Muse, you need
509 to set some options to create your first planner.
511 Muse thinks in terms of projects. Each project consists of a group of
512 documents and certain information associated with these
513 documents. Planner is organized as a project within Muse. So, you need
514 to tell Muse a bit about it.
516 Add something like the following code to your @file{.emacs} file.
518 First, give your new Planner project a name. In this case, we use the
519 name, ``WikiPlanner''.
522 (setq planner-project "WikiPlanner")
525 Next, add an entry for your project to Muse's master list of
526 projects. Don't forget to use your own name here in place of
527 ``WikiPlanner'' if you have chosen something different.
530 (setq muse-project-alist
532 ("~/Plans" ;; where your Planner pages are located
533 :default "TaskPool" ;; use value of `planner-default-page'
534 :major-mode planner-mode
535 :visit-link planner-visit-link)
537 ;; This next part is for specifying where Planner pages
538 ;; should be published and what Muse publishing style to
539 ;; use. In this example, we will use the XHTML publishing
542 (:base "planner-xhtml"
543 ;; where files are published to
544 ;; (the value of `planner-publishing-directory', if
545 ;; you have a configuration for an older version
547 :path "~/public_html/Plans"))))
550 This code should work fine as-is for you as long as the directories
551 you see exist, and as long as you have no other Muse projects besides
554 The first directory (@file{~/Plans}) is the directory where the
555 source files for your planner will reside. This is the directory where
556 you will actually visit files and edit them. These files must have a
559 The second directory (@file{~/public_html/Plans}) is the directory
560 where your planner files will be published by Muse as XHTML
561 (@pxref{Publishing}).
563 After you have added this code, make sure to either evaluate it or
566 @node Components, Advanced Installation, Creating Your Planner, Installation
567 @comment node-name, next, previous, up
570 Now that you have the archive, let's look at what's in it.
572 There should be three directories, named @file{planner}, @file{muse} and
575 In the @file{planner/} directory, you'll see many files with names like
576 @file{planner-gnus.el}. These are extra modules and extensions for
577 Planner, which you can use to tailor Planner to fit your desired
578 planning and information management habits.
580 In the @file{muse/lisp} directory, you'll see many files with names like
581 @file{muse-blosxom.el}. As in @file{planner/}, these are optional
582 modules and extensions.
584 A minimal working installation includes just @file{planner/planner.el}.
586 You need @file{planner.el} because it provides the core functions for
587 handling tasks, notes, and page navigation. You need @file{Emacs Muse}
588 because it provides the functions used to display your pages (both in an
589 emacs buffer and as HTML), and for connecting them to each other. More
590 specifically, it enables you to have hyperlinks and formatting in your
591 emacs buffers even though the actual files you are working with are
592 saved in plain text. These abilities are used in Planner to format your
593 planner pages the way you like, to create links from your tasks and
594 notes to the materials and projects they refer to, and to optionally
595 ``publish'' your pages in different formats, including HTML.
597 In the @file{remember/} directory are files related to
598 RememberMode. RememberMode does not depend on Planner or Muse, but works
599 best with Planner installed. It is not required in order to use Planner,
600 but it is used by many Planner users to record notes and information to
603 If you are curious, you can open each file in these directories and read
604 the comments at the top, to get an idea of what each extension is used
605 for. They are also all detailed later in this manual.
607 @node Advanced Installation, , Components, Installation
608 @comment node-name, next, previous, up
609 @section Advanced Installation
611 Once you decide you want to keep Planner around for a while, there
612 are two additional steps you can take to make using it easier and more
613 efficient. These steps are optional.
616 @cindex installing the info file
617 @cindex @file{planner-el.texi}, installing
618 @cindex @file{planner-el.info}, installing
619 @item You can make this document, the Planner info file, appear in
620 the index of info files you see when you type @command{M-x info} or
621 @kbd{C-h i} in Emacs. The instructions for doing this vary depending
622 on whether you have permission to edit certain files on your
623 system. Follow the instructions in @ref{Installing an Info File, ,
624 ,texinfo, Texinfo}, using something like:
627 * Planner: (path/to/planner/Planner). Organizer/day planner
631 for the new entry in the info @file{dir} file.
633 @cindex byte compiling
634 @item You can byte-compile @file{planner.el}, @file{Muse},
635 @file{remember.el}, or any of the optional modules you frequently use,
636 in order to improve the speed of their execution. Basically, all you
637 need to do is change to the directory of each project in
638 @file{scripts/planner-build.el} and run @command{make} from the command
639 line. To read more detail about byte compilation, see
640 @ref{Byte Compilation, , ,elisp, Emacs Lisp Reference Manual}.
644 @node Overview, Getting Started, Installation, Top
645 @comment node-name, next, previous, up
648 Planner is a plain-text hyperlinked personal information manager
649 for Emacs that helps you keep track of tasks, notes, and other
650 information. People use Planner to support different ways of planning
651 one's day, from Franklin-Covey and David Allen's Getting Things Done
652 to home-brew hacks. Planner is even used to manage information not
653 normally handled by a personal information manager, like bugtracking,
654 time tracking, and team data. If you start by using Planner as a basic
655 TODO and notes manager, you might find other ways it can help you
656 improve your process.
658 You can use Planner to keep track of your tasks, schedule, notes,
659 and other information you want to store in hyperlinkable text files.
660 You can get the most benefit out of a personal information manager if
661 you use it everyday. Most people add @code{(plan)} to the end of their
662 @file{~/.emacs} so that Planner shows today's schedule and
663 unfinished tasks whenever Emacs starts. If you leave your Emacs
664 running for more than 24 hours, try to get into the habit of running
665 @code{plan} at least once a day.
667 Because your time is important, Planner tries to minimize
668 distractions, making it easier for you to jot down tasks and notes
669 without being distracted from your work. People often make tasks based
670 on the current buffer, so Planner tries to create hyperlinks to
671 whatever you're looking at so that you can jump back to it easily. The
672 @ref{Getting Started} tutorial will show you how to set that up for
673 both tasks and notes.
675 The customizability of Planner means you can make your personal
676 information manager truly personal. Planner strives to be as flexible
677 as possible, and we would love to adapt Planner to fit your needs.
678 Browse through our mailing list (@pxref{Getting Help}) to
679 find out how other people are using Planner, and post your feature
680 requests and bug reports there!
682 Planner is just a tool. It does not dictate a particular way of
683 planning, although it supports some ways better than it supports
684 others. If you want to take some time thinking about planning, read
685 the following reflections for inspiration and ideas. On the other
686 hand, if you want to hit the ground running, see @ref{Getting
687 Started}. If you already have a specific way of planning in mind,
688 check out @ref{Sample Configuration Files}.
691 * Planning based on the Franklin-Covey Approach::
695 @node Planning based on the Franklin-Covey Approach, Why Use Planner, Overview, Overview
696 @comment node-name, next, previous, up
697 @section Planning Based on the Franklin-Covey Approach
698 @cindex philosophy of planning
700 This is a slightly edited and updated version of an essay by John
701 Wiegley. Read it if you want to get some insights into one way of
702 planning. You can skip this if you want to go straight to planning
705 What is planning? It can be a nebulous thing to define. In its
706 essence, however, it is very simple: it's how we achieve our dreams.
708 Our days are filled with time, and hence with actions, whether they
709 be of a mental or physical sort. But there are two kinds of
710 action: reactive and creative. Reactive action is a response to
711 the environment, a reaction to stimulus. Had we enough instincts
712 to ensure survival, we could live according to this kind of action
713 alone. It is a mode of behavior we share with every living
716 The opposite to reactivity is creativity, when we decide upon a
717 course of action that is a wholly a product of personal choice. We
718 then make decisions as to the steps needed to make this wish a
719 reality. This is planning. Planning is essentially a creative
720 endeavor at every step.
722 First, create the idea, what you want to achieve. Very short-term
723 ideas do not need much more than thinking about how to do it. But
724 long-term ideas require planning, since the mind cannot contain all
727 Second, decide how the idea maps into the circumstances you find
728 yourself in. Some environments will assist your plan, others
729 hinder it. But step by step, identify every barrier to the
730 realization of your idea, and devise a countermeasure to overcome
731 it. Once you've mapped things out from beginning to end,
732 accounting for unknowables as best you can, you now have your plan.
734 Third is to break the stages of the plan into parts that are not
735 overwhelming in their complexity. It is at during this phase that
736 a plan is turned into task items, each to be accomplished within
737 the span of one day's time. If a task requires several days, break
738 it up further. The smaller it is, the less your mind will recoil
741 Fourth is to monitor your progress, identifying problems and
742 correcting for them as you go. Some plans start out unachievable,
743 and remain that way indefinitely, due to a simple lack of
744 observation. If nothing is working for you, change it. Otherwise,
745 your plan is merely a well-crafted wish.
747 Fifth is just to do the work, and be patient. All good plans take a
748 great deal of time, and *cannot* happen immediately. The groundwork
749 must be laid for each step, or else it will rest on an unsecure
750 foundation. If you follow your plan doggedly, applying some time to
751 it each day or week, it @emph{will} happen. Remember the story of the
752 tortoise and the hare. I've even written a short essay on the
753 necessity of gradual accomplishment, which can be found at
754 @url{http://emacswiki.org/johnw/essays/node2.html}.
756 How can this software help? Computers are ideal for manipulating
757 information, since they allow you to change things without erasing
758 or rewriting. And since all plans change quite a bit during their
759 implementation, a planning program can be very helpful.
761 Start by adding the following to your @file{.emacs} (or @file{_emacs}):
767 Now, conceive your idea. I can't believe there's nothing you want
768 from life. More peace, time to enjoy the world, an end to war?
769 Everyone wants something. Search deeply, and you will find
770 countless unhoped wishes lurking therein. Choose one for now, and
771 think on it for a while.
773 Then open a file (using @kbd{C-x C-f}) within the directory named by
774 @code{planner-directory}. Emacs will automatically recognize this file
775 as a planner file. Name the file after your plan, such as
778 Choose an idea you really want to accomplish. Struggle to
779 differentiate between the things you want because others want them,
780 and the things you want for yourself. It takes quite an effort, and
781 may require a long time before you notice the difference. Many people
782 want to be more healthy to be more attractive, which is an externally
783 driven goal. Unless @emph{you} really want to accomplish what you
784 envision, the odds are you will fail. Only our own wishes and dreams
785 possess enough personal energy to see themselves to fruition. What
786 happens to many of us is simply that we never become conscious of
787 these dreams: what we love, what we desire most. When I talk to
788 friends, so much of what I hear is things they want because they feel
789 they should want them. There's just not enough energy there to pursue
790 a good plan, because nearly all of it is negative energy.
792 Do you know what you really want? Don't worry, many people don't.
793 It's not a question anyone really wants us to pursue, because often
794 we don't want what others do; it doesn't contribute to the social
795 welfare, and all that nonsense. Somehow we always forget that
796 what's good for the social welfare now, was someone else's crazy
797 dream a hundred years ago. The human aversion to fundamental
798 change is always one's greatest enemy, so don't waste any time
799 getting bitter about it.
801 For the sake of argument I assume you really do want to be
802 healthier, because you've fallen in love with the ideal of purity,
803 or you understand the connection between your physical self and the
804 world around you, and how this can open up your spirit to desiring
807 So you're in a Wiki file called @file{BetterHealth}. Start typing.
808 Type anything related to your idea: what you think about it, your
809 ideas on it, @emph{and especially what the end will look like}. If
810 you can't visualize the end, you can't plan, since planning is about
811 drawing a line between now and then.
813 When you've typed enough to gain a vision of your goal, start
814 drafting what the possible intermediate steps might be. Then stop,
815 get up, walk around, enjoy life, and come back to it. Taking a
816 long time at the beginning is not a bad idea at all, as long as
819 As you chew on your idea, it will begin to become more and more
820 concrete. You'll have ideas about the smallest pieces, and ideas
821 about the biggest pieces. Keep going until it starts to take shape
822 before you, and you can see yourself in your mind's eye moving from
823 the present into the future. Write down this progression, and the
824 sorts of things you might encounter along the way.
826 As you continue, you'll naturally discover discrete phases, or
827 ``milestones'' as managers love to call them. These are very
828 important, because they let you know you're making progress. I
829 recommend having a big party with friends every time you achieve a
830 milestone. A typical plan might have between three and ten.
832 Between the milestones are the bigger pieces of your plan. Name
833 these pieces using MixedCase words, and you'll notice that Emacs
834 colors and underlines them for you. Like, FindGoodGym. Hit return
835 on this highlighted word, and you'll find yourself in another,
836 blank file. In this file, start drafting your sub-plan, just as
837 you did with the larger plan. You should find it easier now, since
838 the scope is smaller.
840 As you break down further, you'll notice simple little things that
841 need to get done. These are your tasks. Every plan is a
842 succession of tasks. The difference from reactivity is that each
843 task is part of the larger plan. This is what it means to be
844 systematic: that everything you do helps further your plan. If you
845 have tasks in your day that contribute to no plan, they are
846 reactive. Of course, life is full of these, but don't let them
847 take up more than 20% of your day. If you allow yourself to be
848 dominated by reactive tasks, you'll regret it at the end of your
849 life. I don't know this personally, but I do know that striving
850 for one's dreams -- and seeing them come to fruition -- is the
851 greatest joy a man can possess. It is the essence of freedom, of
852 living, of creation. Reactivity is the opposite of this, and
853 serves only to drain our energy and slacken our spirits.
855 Now that you've thought of a simple task, type @kbd{C-c C-t}. This
856 will ask for a brief description of the task, and when you plan to do
857 it. If you hit @key{RETURN} at the question @samp{When}, it assumes
858 you mean today. It will also pop up a three-month calendar at this
859 question, so you can see where your free days are. Make sure you set
860 the variable @code{mark-diary-entries-in-calendar} to @samp{t} in your
861 @file{.emacs} (or @file{_emacs}) file. This way, you can see which
862 days your appointments fall on. (Read about the Emacs Calendar and
863 Diary in @ref{Calendar/Diary, , , Emacs, GNU Emacs Manual}.)
866 (setq mark-diary-entries-in-calendar t)
869 Once your task is in there, go back to your plan and keep
870 generating more tasks. Generate them all! Fully describe---as
871 tasks---everything necessary to bring your sub-plan to completion.
872 Don't create tasks for the other sub-plans. You may have good idea
873 of what they'll look like, but don't bother rendering them into
874 tasks just yet. Things will change too much between now and then,
875 for that to be a good use of your time.
877 Is your sub-plan now rendered into all of the tasks necessary to
878 reach your first milestone? Great! That is the purpose of
879 planner.el. The rest is really up to you. If you find that you
880 keep putting things off, and never do them, that's the surest sign
881 you're planning for someone else's dream, and not your own.
883 Here are some of the things planner.el can do, to help you manage
884 and track your tasks:
886 At the beginning of every day, type @kbd{M-x plan}. This will jump
887 you to the top of the most recent task list before today. If you
888 skipped a bunch of days, you'll have to open up those files on your
891 Probably some of the tasks that day won't be finished -- that's OK.
892 Learning to properly estimate time is a magical, mystical art that few
893 have mastered. Put your cursor on those undone tasks, and type
894 @kbd{C-c C-c}. This will move them into today's task page. You can
895 jump to today's task page at any time by typing @kbd{C-c C-n} (from a
896 Wiki or planning page). I heartily recommend binding @kbd{C-c n}, to
897 jump you to this page from anywhere:
900 (define-key mode-specific-map [?n] 'planner-goto-today)
903 As you look at your task sheet each day, the first thing to do is to
904 ``clock in'' to one of them. This isn't necessary, and is only
905 helpful if you're around your computer a lot. But by typing @kbd{C-c
906 C-i} (assuming you have my @file{timeclock.el} on your load-path), it
907 will log the time you spend working on your sub-plan (@pxref{Time
908 Intervals, , , Emacs, GNU Emacs Manual}). This is helpful for viewing
909 your progress. Type @kbd{C-c C-o} to clock out.
911 @kbd{C-M-p} and @kbd{C-M-n} will move a task up and down in priority.
912 Priority is represented by a letter A through C. 'A' tasks mean they
913 must be done that day, or else your plan is compromised and you will
914 have to replan. 'B' means they should be done that day, to further the
915 plan, otherwise things will be delayed. 'C' means you can put off the
916 task if you need to, although ultimately it will have to be done.
918 For reactive tasks, the letters mean something different: 'A' means
919 you must do it today, or somebody will roast your chestnuts over an
920 open fire. 'B' means you should do it today, or else someone will
921 be practicing patience at the day's end. 'C' means no one will
922 notice if you don't do it.
924 Again, reactive tasks are ENEMIES OF PLANNING. Really, until you
925 see them that way, circumstances will push you around and steal
926 your life away. We have only so many years to use, and everyone is
927 greedy to take them. It's insidious, almost invisible. A healthy
928 dislike of reactivity will do wonders for organizing your affairs
929 according to their true priority.
931 The last word that needs to be said concerns ``roles''. Every person
932 stands in several positions in his life: husband, employee, manager,
933 etc. These roles will tend to generate tasks not associated with any
934 immediate plan, but necessary to maintain the health and functioning
935 of the role. My suggestion is to keep this the smallest possible
936 number, and fulfill those that remain well. How you decide to
937 apportion your time between pursuing grand designs, and fostering deep
938 relationships, is a personal matter. If you choose well, each will
941 I mention this to point that reactivity is something not
942 exclusively associated with tasks that have no master plan, because
943 being a father, for example, is something that rarely proceeds
944 according to orderly plans. But the role of father itself is its
945 own plan, whose goal is ``to be the best one can'', and whose
946 component tasks are spending time on whatever comes up. It is, in
947 a sense, an implicit plan. But reactive tasks follow no plan at
948 all; they are parasites of time that suck the spirit away, whereas
949 properly chose roles actually help fulfill one's own inner needs.
950 At least, this is what I believe.
952 @defun plan force-days
953 Start your planning for the day, beginning with the last day's tasks.
955 If @code{planner-carry-tasks-forward} is non-nil, find the most recent
956 daily page with unfinished tasks and reschedule those tasks to
957 the current day. If @var{force} is non-nil, examine all past daily
958 pages for unfinished tasks.
960 If @code{planner-carry-tasks-forward} is nil, visit the most recent
961 daily page. If a daily page for today exists, visit that instead.
963 If @var{force-days} is a positive integer, scan that number of days.
964 If @var{force-days} is @samp{t}, scan all days.
968 @node Why Use Planner, , Planning based on the Franklin-Covey Approach, Overview
969 @comment node-name, next, previous, up
970 @section Why Use Planner?
971 @cindex Planner, why use
973 You can skip this essay if you just want to get started, or read it
974 for some insights into why the previous maintainer is crazy about it.
976 Why I Use Planner, by Sacha Chua
978 I thought about why I liked Planner. Planner as a TODO manager
979 isn't particularly special. Although I can assign tasks to categories
980 and see a breakdown of what projects are taking up my time, Evolution
981 and Microsoft Outlook provide more powerful task support. In other
982 task managers, you can e-mail tasks, assign multiple categories and
983 fill in all sorts of metadata. You can even synchronize your tasks
984 with devices like a phone or PDA. So why use Planner?
986 I realized that integration into my way of life and automatic context
987 clues are what really make planner tasks worth it for me. I don't have
988 to switch to another application to create a task. I can just hit a
989 keyboard shortcut. Planner uses a minibuffer to get the task
990 description. My windows are not rearranged in any way, and I can look
991 at the data that's relevant to a task. Not only that, tasks
992 automatically pick up context clues, like whom I'm talking to on IRC
993 or the file I'm editing at the moment. This cuts down on the explicit
994 context I need to include and makes it easier for me to bring up the
997 As a scheduler, Planner is also not particularly distinguished.
998 Sure, it can display my @file{~/diary}, but for that matter so can
999 @kbd{M-x diary}. Evolution and Outlook can give me a more graphical
1000 view of my time, sync with my PDA, and coordinate my schedule with
1001 other people. Those applications support detailed schedule entries
1002 with powerful cyclic options. On the other hand, Planner gives me
1003 a personal, plain text view and (at least the way I use it) requires
1004 me to edit a separate file to add new appointments. (I've defined a
1005 few shortcut keys to deal with this.) However, it does have one
1006 advantage---my schedule is always loaded. I used to use Outlook on
1007 Windows, but having my schedule in a separate application meant that I
1008 actually looked at it very rarely, as I had turned off reminders
1009 because they got annoying.
1011 Planner's notes, however, are what really convinced me. I can hit
1012 a keyboard shortcut from anywhere and type my notes into a buffer
1013 which automatically keeps context information. After typing the note,
1014 I can then categorize it. I think that the critical thing here is that
1015 interruptions---fleeting thoughts---don't break my flow. I can just
1016 pop up a remember buffer, stow that thought away somewhere, and go
1017 back to it whenever I want. In contrast, creating a note in Outlook
1018 means switching out of my application, making a couple of keystrokes,
1019 typing the note in, and then switching back. The context switches make
1020 it hard to keep track of where I am and what I'm supposed to remember.
1021 Not only that, I need to enter context by hand. Even though I can
1022 color my notes and reorganize them in Outlook, I find the context
1023 switch too expensive. I used to keep notes in other knowledge
1024 management tools as well. Some applications allowed me to
1025 drag-and-drop links into the current note, and that was cool. But that
1026 required a manual action, and those applications didn't feel
1027 integrated into my way of working. (Note: You'll need remember.el for
1030 I guess that's why I like Planner. Unlike other organizers which
1031 don't know anything about the applications I use, Planner tries
1032 its best to integrate into the way I work, and it's easy to extend.
1033 Fortunately I do almost all my work in Emacs, so I can think of my
1034 organizer as integrated into my e-mail client, Internet Relay Chat
1035 client, web browser, file editor and even games. It automatically
1036 picks up context clues from these applications and allows me to easily
1037 jump back to relevant files. It doesn't distract me. It allows me to
1038 key in data and then it gets out of my way.
1040 (That said, it's perfectly okay to use Planner even if you don't live
1043 The processing that happens in the background is a bonus, and
1044 publishing my task list and notes online has greatly helped me. It
1045 gives other people a way to see what I'm working on and what I've
1046 planned for the future. Occasionally people write in with additional
1047 resources and helpful tips. (Again, this is purely optional. Many
1048 people don't publish their planner pages. Other people use really
1049 fine-grained access control.)
1051 I think the greatest feature of Planner, though, is its user
1052 community. Because Planner can be easily modified, we can experiment
1053 with a lot of new ideas quickly, and we can tailor Planner to fit our
1054 needs. I love checking my @samp{planner-el-discuss} mail and finding
1055 out how people have tweaked Planner or would like to tweak Planner,
1056 and I've learned a lot by exchanging reflections on organizing one's
1059 I really wasn't an organization freak before I started using Planner.
1060 I often forgot to do my homework or answer important mail. I still
1061 procrastinate now, but at least it's all being kept track of
1062 somewhere! I also really like how Planner lets me to gradually improve
1063 how I'm doing things, and I feel I've come a long way.
1065 Please try it out! We'd love to hear how Planner can become
1066 @emph{your} personal information manager.
1068 @node Getting Started, More about Planner, Overview, Top
1069 @comment node-name, next, previous, up
1070 @chapter Getting Started
1072 At the end of this tutorial, you will be able to use Planner and
1073 related modules to keep track of your tasks, schedules and notes, all
1074 within the convenience of Emacs.
1076 There are two kinds of pages in a Planner wiki. Day pages show tasks,
1077 schedule, and notes for the day, while plan pages organize related tasks
1078 and notes into a single page.
1080 If you have not yet added planner to your @file{~/.emacs}, add the
1084 (add-to-list 'load-path "/path/to/muse/lisp")
1085 (add-to-list 'load-path "/path/to/planner")
1086 (add-to-list 'load-path "/path/to/remember")
1090 This will bring up the most recent day page with unfinished tasks or
1091 create a new day page if necessary. By default, planner pages are
1092 stored in @samp{~/Plans} (@code{planner-directory}).
1103 @node Tasks, Schedule, Getting Started, Getting Started
1106 Let us start by creating a task labelled
1109 Join http://mail.gna.org/listinfo/planner-el-discuss/
1112 From anywhere (even this info buffer!), call @kbd{M-x
1113 planner-create-task-from-buffer} to create a new task. Fill in the
1114 description and choose a date by:
1117 @item typing 1 - 31 to put the task on that day of the month,
1118 @item accepting the default (today) by pressing RET,
1119 @item selecting the date with mouse-1,
1121 typing +n (where in is an integer) to schedule the task in n days time,
1123 @item typing nil to make an undated task.
1126 For now, accept the default (@samp{today}) by pressing @key{RET}.
1128 You will then be prompted for a plan page. Plan pages gather related
1129 tasks and notes, giving you an overview of what you've done so far.
1130 You can accept the default TaskPool, create your own plan page, or
1131 specify nil to make a task that is not associated with a plan page.
1132 For now, accept the default (@samp{TaskPool}) by pressing RET.
1134 You have created your first task. View today's page with
1135 @kbd{M-x planner-goto-today}. You will see a line of the form
1138 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
1141 If you created the task from this page, then there will be an additional
1145 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ : Tasks (TaskPool)
1148 The URL, @samp{TaskPool} and @samp{Getting Started} are
1149 hyperlinks. You can use TAB and S-TAB to navigate between them and RET
1152 Create more tasks using @kbd{M-x planner-create-task-from-buffer}.
1153 This is bound to @kbd{C-c C-t} in @code{planner-mode} pages
1154 for your convenience. For example, create the following tasks:
1158 @samp{Describe my current way of working and how I would like to work},
1159 for three days from now (@samp{+3}),
1161 @samp{Learn how to schedule a task}, an undated task (@kbd{nil}) on the
1164 @samp{Browse through the Planner info manual} for today (@kbd{.} or
1165 accept the defaults), and
1167 @samp{Add (plan) to the end of my [[~/.emacs]]} for today, but without a
1168 plan page (specify @kbd{nil} at the plan page prompt)
1171 Tip: I bind planner-create-task-from-buffer to "F9 t" so that I can
1172 easily call it from anywhere. You can do that with this elisp fragment:
1173 @code{(global-set-key (kbd "<f9> t") 'planner-create-task-from-buffer)}
1175 Next, visit the TaskPool by:
1179 @key{TAB}-bing or using the cursor and typing @key{RET} to follow the
1181 @item @kbd{C-x C-f TaskPool RET} to use @code{find-file}, or
1182 @item @kbd{C-c C-f TaskPool RET} to use @code{muse-project-find-file}
1185 You can see an overview of the tasks as scheduled on different days.
1186 Unlike many personal information managers that store all of your data
1187 in one file and then perform magic in order to present different
1188 views, Planner uses plain text files. The data is duplicated and kept
1189 updated by functions. This makes it simpler and easier to modify,
1190 because what you see is (almost) what you get. On the other hand,
1191 you'll need to get used to either editing both files, or using the
1192 built-in functions for editing and updating files. If you prefer not
1193 to work with linked tasks, you can configure Planner to use only plan
1194 pages or use only day pages.
1196 The TaskPool page should list the tasks you created earlier. Go to the
1197 one named Learn how to schedule a task . Type @kbd{C-c C-c}
1198 (@code{planner-copy-or-move-task}) to schedule the task. Type RET to
1199 accept the default (today). Go to the day page by following the link
1200 or calling @kbd{M-x planner-goto} (@kbd{C-c C-j C-d} or the menu bar);
1201 you will see the newly-created task there. You can also use @kbd{C-c
1202 C-c} (@kbd{planner-copy-or-move-task}) to reschedule a task to an
1203 earlier or later date.
1205 Well, that task is done. To mark the task as completed, type @kbd{C-c
1206 C-x} (@code{planner-task-done}). You can also edit the status manually
1207 (change _ to X) as long as you remember to call @kbd{M-x
1208 planner-update-task} to update the link page as well. Updating relies on
1209 the task description being the same, so do not edit this manually.
1211 Quick summary of commands:
1215 Go to today's page: @kbd{M-x plan} to carry unfinished tasks forward, or
1216 @kbd{M-x planner-goto-today} to just go to today's page.
1218 Create a task: @kbd{C-c C-t} (@code{planner-create-task-from-buffer}),
1219 or type a task manually (call M-x planner-update-task if the task is
1222 Mark a task as done: @kbd{C-c C-x} (@code{planner-task-done}), or edit
1223 the task and call @kbd{M-x planner-update-task}
1224 @item Edit a task description: @kbd{M-x planner-edit-task-description}
1225 @item Reschedule a task: @kbd{C-c C-c} (@code{planner-copy-or-move-task})
1227 Reschedule many tasks: Mark a region and use @kbd{M-x
1228 planner-copy-or-move-region}
1230 Change the plan of a task: @kbd{M-x planner-replan-task}, or do
1231 @kbd{C-c C-c} (@code{planner-copy-or-move-task}) and type in a
1232 plan page rather than a date
1233 @item Delete a task: @kbd{M-x planner-delete-task}
1235 Reorder tasks: @key{M-p} (@code{planner-raise-task}) and @key{M-n}
1236 (@code{planner-lower-task}), or normal editing commands like kill and
1238 @item Change task priorities (@samp{#A} > @samp{#B} > @samp{#C}):
1239 @key{C-M-p} (@code{planner-raise-task-priority}) and
1240 @key{C-M-n} (@code{planner-lower-task-priority}),
1241 or edit the task and call @kbd{M-x planner-update-task}.
1244 You can save your tasks with @kbd{C-x C-s} the same way you save any
1245 other file, or Emacs will prompt you to save it when you exit.
1247 @node Schedule, Notes, Tasks, Getting Started
1248 @comment node-name, next, previous, up
1251 This is free-form. You can put anything you want into this, or remove
1252 it from @code{planner-day-page-template} entirely. Some people use it
1253 to keep track of their plans for the day with tables like this:
1256 hh:mm | hh:mm | activity
1257 hh:mm | hh:mm | activity
1258 hh:mm | hh:mm | activity
1261 Remember, Planner files are just plain text. You can add new sections
1262 or remove old ones, or use the suggested sections for entirely
1263 different activities.
1265 @node Notes, Hyperlinks, Schedule, Getting Started
1266 @comment node-name, next, previous, up
1268 @cindex @file{remember.el}
1269 @cindex @file{remember-planner.el}
1272 By default, your Planner pages will have a Notes section. You can put
1273 anything you want in this section, or remove it from your
1274 @code{planner-day-page-template} entirely.
1276 You may be interested in @file{remember-planner.el}, part of the
1277 Remember package (see @inforef{Top, remember-el, remember-el}). You
1278 can download Remember at @uref{http://gna.org/projects/remember-el/}).
1280 @code{remember-planner.el} makes it easy to create notes from anywhere
1281 in Emacs, and it uses the same context-sensing code that Planner uses.
1282 Notes added by @code{remember-planner.el} look like this:
1288 [[context hyperlink]]
1291 and are outlined at the H2 level in published HTML.
1293 You can easily create context-aware notes if you include the following
1294 in your @file{~/.emacs}:
1297 (require 'remember-planner)
1298 (setq remember-handler-functions '(remember-planner-append))
1299 (setq remember-annotation-functions planner-annotation-functions)
1302 Then @kbd{M-x remember} will open a dedicated buffer for you to write
1303 your note. If Planner recognizes your current buffer as one with
1304 context then it will include a hyperlink at the bottom of the note.
1305 The first line of the note is used as a title, so make it short and
1306 meaningful. The rest of the text will be used as the body. Try it now
1307 by creating a note, perhaps about things you'd like to remember from
1310 Typing @kbd{C-c C-c} after composing will prompt for a plan page to
1311 put the note on, with auto-completion. If you don't enter a page, the
1312 note will just be saved on today's page. If you do specify a plan
1313 page, the note will go on both today's page and on the specified page.
1314 Let's try specifying @samp{TaskPool} for the note.
1316 If you look at today's page, you'll find a timestamped note that links
1317 to @samp{TaskPool}. Likewise, @samp{TaskPool} contains a note that
1318 links to today's page. To change the plan page of a note, use
1319 @kbd{planner-replan-note}.
1321 If you decide to edit the note on one of these pages after it has been
1322 saved, be aware that your changes will not be automatically reflected
1323 on the linked page. To update the linked page after editing a note,
1324 use @kbd{M-x planner-update-note}.
1326 @node Hyperlinks, Example Page, Notes, Getting Started
1330 Planner automatically creates context-sensitive hyperlinks for your
1331 tasks and notes when you use @code{planner-create-task-from-buffer}
1332 and @code{remember}.
1334 Blue links indicate URLs and Planner pages that already exist. Red links
1335 indicate Planner pages that have not yet been created.
1337 Middle-click or type @key{RET} on any link to view the link in the
1338 current window. Shift-middle-click or type @key{S-RET} to view the
1339 link in another window. @key{TAB} goes to the next link, while
1340 @key{S-TAB} goes to the previous one.
1342 You can pick up hyperlinks using the @code{planner-annotation-as-kill}
1345 @defun planner-annotation-as-kill
1346 Create a context-sensitive hyperlink for the current buffer and copy
1347 it to the kill ring. When called with a prefix argument, prompt for
1348 the link display name.
1351 You can then paste it into any Planner buffer by using @kbd{M-x yank}
1352 or the keyboard shortcut.
1354 Alternatively, you can create hyperlinks by typing them directly, using
1355 the syntax defined by Muse. Anything inside double square brackets will
1356 be treated as a link. For example, if you type @samp{[[GroceryList]]} in
1357 a Planner buffer, you will end up with a link to a page called
1358 @samp{GroceryList}. @inforef{Implicit Links, Bare URLs WikiNames and
1359 InterWiki links, muse}, for more information about Muse syntax.
1361 Hyperlinks are a powerful feature of Planner. You can use them to
1362 hyperlink to mail, news, Web pages, and even IRC connections. See the
1363 section on @ref{Managing Your Information} to find out how to enable
1364 support for various parts of Emacs. Want to add a new hyperlink
1365 scheme? Check out the source code for examples or ask on the mailing
1368 @node Example Page, Review, Hyperlinks, Getting Started
1369 @comment node-name, next, previous, up
1370 @section Example Page
1371 @cindex example page
1372 @cindex planning page, example
1374 An example planner file is given below. You'll notice that Planner
1375 does not have a well-defined user interface. Rather, it's free-form
1376 and open, allowing you to adapt it to your preferences.
1379 ----------------------------------------------------------------------
1382 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
1383 #B _ Browse through the Planner info manual (TaskPool)
1384 #B _ Add (plan) to the end of my ~/.emacs
1385 #B X Learn how to schedule a task (TaskPool)
1389 18:00 | 19:00 | Learn how to use Planner
1393 Notes are free-form. You can put anything you want into this.
1395 .#1 This is note number one
1397 Notes on note number one!
1399 .#2 This weird ".#2" syntax is used for allout.el enumerated lists
1401 It makes using allout-mode very handy.
1405 @node Review, , Example Page, Getting Started
1406 @comment node-name, next, previous, up
1411 @item @emph{Ideas for using planner more effectively:}
1415 Add @code{(plan)} to the end of your @file{~/.emacs} so that you are
1416 reminded about your tasks every day.
1419 Bind useful functions to shortcut keys and get used to creating tasks
1420 and notes from anywhere.
1423 Think about how you plan your day and look for ways to improve it. Ask
1424 the mailing list (@pxref{Getting Help}) for tips.
1427 Browse the rest of this manual, the source code, and other resources on
1428 the Net for tidbits you can use.
1433 @item @emph{Useful functions outside planner buffers:}
1436 @item @code{planner-create-task-from-buffer}
1437 @item @code{remember}
1438 @item @code{planner-goto-today}
1439 @item @code{planner-goto}
1443 @item @emph{Useful functions inside planner buffers:}
1446 @item @kbd{C-c C-t} (@code{planner-create-task-from-buffer})
1447 @item @kbd{C-c C-x} (@code{planner-task-done})
1448 @item @kbd{M-x planner-edit-task-description}
1451 @kbd{C-c C-c} (@code{planner-copy-or-move-task}), @kbd{M-x
1452 planner-copy-or-move-region}
1454 @item @kbd{M-x planner-replan-task}
1455 @item @kbd{M-x planner-delete-task}
1458 @key{M-p} (@code{planner-raise-task}) and @key{M-n}
1459 (@code{planner-lower-task})
1461 @item @key{C-M-p} (@code{planner-raise-task-priority}) and
1462 @key{C-M-n} (@code{planner-lower-task-priority}),
1463 @item @code{planner-replan-note}
1464 @item @code{planner-update-note}
1469 That's all you need to know in order to use Planner as a basic TODO and
1470 notes manager, but there's a whole lot more. Read through this manual
1471 and our mailing list archives (@pxref{Getting Help}) for lots of
1472 wonderful ideas about planning in Emacs!
1474 @node More about Planner, Managing Your Information, Getting Started, Top
1475 @comment node-name, next, previous, up
1476 @chapter More about Planner
1480 * More about Tasks::
1481 * More about Notes::
1482 * Making Files Pretty::
1484 * Interactive Lisp:: planner-lisp.el
1485 * Publishing:: planner-publish.el
1486 * Experimental Functions:: planner-experimental.el
1489 @node Navigation, More about Tasks, More about Planner, More about Planner
1490 @comment node-name, next, previous, up
1491 @section Starting with Day Pages
1493 @command{planner-goto-today} opens today's page. Day pages are named
1494 @samp{YYYY.MM.DD} and contain your notes for the day.
1496 You should see a file that looks like this:
1507 You can type anything you want into this file. You can add or delete
1508 sections. When you save, Emacs stores your information in
1509 @code{planner-directory}.
1511 Use the following commands to navigate through day pages:
1514 Start planning the day. If @code{planner-carry-tasks-forward} is
1515 non-nil, copy the most recent unfinished tasks to today's page, else
1516 open the most recent page.
1519 @defun planner-goto (@kbd{C-c C-j C-d})
1520 Prompt for a date using a calendar pop-up and display the
1521 corresponding day page. You can specify dates partially. The current
1522 year and month are used if omitted from the input. For example, if
1523 today is 2004.05.05, then
1526 @item @kbd{+1} is one day from now, or @samp{2004.05.06}
1527 @item @kbd{-1} is one day before now, or @samp{2004.05.04}
1528 @item @kbd{12} is equivalent to @samp{2004.05.12}
1529 @item @kbd{8.12} is equivalent to @samp{2004.08.12}
1530 @item @kbd{2005.08.12} is a full date specification
1533 In the calendar buffer, you can also left-click or press @key{RET} on
1534 a date to select it.
1537 @defun planner-goto-today (@kbd{C-c C-j C-j})
1538 Display today's page. Create the page if it does not yet exist.
1541 @defun planner-goto-tomorrow (@kbd{C-c C-j C-t})
1542 Goto the planner page days @var{after} the currently displayed date.
1543 If @var{days} is nil, go to the day immediately after the currently
1544 displayed date. If the current buffer is not a daily planner page,
1545 calculate date based on today.
1548 @defun planner-goto-yesterday (@kbd{C-c C-j C-y})
1549 Goto the planner page @var{days} before the currently displayed date.
1550 If @var{days} is nil, go to the day immediately before the currently
1551 displayed date. If the current buffer is not a daily planner page,
1552 calculate date based on today.
1555 @defun planner-goto-most-recent
1556 Go to the most recent day with planning info.
1559 @defun planner-goto-previous-daily-page
1560 Goto the last plan page before the current date.
1561 The current date is taken from the day page in the current
1562 buffer, or today if the current buffer is not a planner page.
1563 Do not create pages if they do not yet exist.
1566 @defun planner-goto-next-daily-page
1567 Goto the first plan page after the current date.
1568 The current date is taken from the day page in the current
1569 buffer, or today if the current buffer is not a planner page.
1570 Do not create pages if they do not yet exist.
1573 @defun planner-goto-plan-page page
1574 Opens @var{page} in the the @code{planner-project} Wiki. Use
1575 @code{planner-goto} if you want fancy calendar completion.
1578 @defun planner-show date
1579 Show the plan page for @var{date} in another window, but don't select
1580 it. If no page for @var{date} exists, return nil.
1584 @node More about Tasks, More about Notes, Navigation, More about Planner
1585 @comment node-name, next, previous, up
1586 @section More about Tasks
1587 @cindex tasks, more about
1589 This section is divided into three parts. In the first part, you can
1590 read about all the options, strategies and commands to help you
1591 efficiently add new tasks to your planner. In the second part, we'll go
1592 over all of the aspects of Planner that relate to organizing, editing,
1593 rescheduling and viewing the tasks you've already created. Finally,
1594 we'll cover some ways to step back and look at various reports and
1595 overviews that can be generated from your planner pages.
1597 You may also be interested in tracking time spent on tasks with
1598 @ref{Timeclock} and estimating project completion time with
1599 @ref{Schedule} (also see @pxref{schedule.el}).
1602 * Creating New Tasks::
1603 * Organizing Your Tasks::
1604 * Task Reports and Overviews::
1607 @node Creating New Tasks, Organizing Your Tasks, More about Tasks, More about Tasks
1608 @comment node-name, next, previous, up
1609 @subsection Creating New Tasks
1610 @cindex tasks, creating
1612 Planner makes it very easy to quickly add something to your list of
1613 tasks. Once you get used to the basics of
1614 @command{planner-create-task-from-buffer}, you might want to take a
1615 closer look at some things in Planner that can help you create new tasks
1616 in a way that fits with your system.
1621 * Task IDs:: planner-id.el
1622 * Cyclic Tasks:: planner-cyclic.el
1624 * Deadlines:: planner-deadline.el
1627 @node Creating a Task, Task Priorities, Creating New Tasks, Creating New Tasks
1628 @comment node-name, next, previous, up
1629 @subsubsection Creating a Task
1630 @cindex tasks, creating
1632 You can create a task from any buffer in Emacs by invoking
1633 @command{M-x planner-create-task-from-buffer}.
1635 This command does more than just add an item to your list of tasks. It
1636 also connects that item to some useful context information.
1638 If you create a task while viewing any buffer other than a Planner
1639 day page, Planner will associate the task with a hyperlink to that
1640 buffer. Try it now by creating a task from this Info buffer.
1643 @item @kbd{M-x planner-create-task-from-buffer}
1645 When prompted for the task name, enter @kbd{Learn how to change a task's
1646 status} and press @key{RET}.
1649 When prompted for the date, press @key{RET} to schedule the task for
1653 When prompted for the project page, press @key{RET} to accept the
1654 default page of @samp{TaskPool}. This is a page for tasks not connected
1659 Planner prompts you for two pieces of information when you ask it
1660 to create a task. First, it asks you when you would like to have the
1661 task show up in your planner. If you would like it to be scheduled for
1662 today, you can just hit @key{RET}. If you would like it to be
1663 scheduled for some day during the current month, you can just enter
1664 the date, without the month, like @samp{16}. If you would like it to
1665 be scheduled for some day in a future month of the current year, you
1666 can enter just the month and date, like @samp{06.16}. If you would
1667 like to schedule something for next year, then enter the full date,
1668 like @samp{06.16.2005}. If you do not want this task to appear on a
1669 day page at all, you can enter @samp{nil}.
1671 The second piece of information Planner asks for is the name of
1672 the project to associate the task with. In the above example, you
1673 associated the task with the project ``TaskPool'', which means that
1674 you did not want to associate the task with a particular project or
1675 goal in your life. Another way to do this is to answer the project
1676 prompt by entering @samp{nil}. But instead, you might enter
1677 @samp{LearnPlanner} as the project. This creates a new page called
1678 ``LearnPlanner'' in your planner directory and places an entry for the
1681 The task then exists in two places: once on your day page, to show how
1682 it fits into your daily work; and once on a project page, to show how
1683 it fits into your larger projects and goals. In the future you might
1684 add related tasks like, ``Memorize Planner keybindings''. These
1685 tasks might be scattered over weeks or months worth of day pages, but
1686 as long as you enter the same project name for each, you will have a
1687 way to look at them all together on a single project page.
1689 Planner also creates hyperlinks to enable you to easily move back
1690 and forth between the day page system and the project page
1691 system. Each task on a day page will have a hyperlink to its project
1692 page. Each task on a project page will have a hyperlink to its day
1695 After using Planner for a while, you may find yourself with quite
1696 a few project pages. Keep in mind that completion is enabled at the
1697 project prompt when you create a task, so hitting @kbd{SPC} or
1698 @kbd{TAB} at the prompt will show you a list of your current project
1701 Once the task is created, you are returned to the buffer you were
1702 working in again, Planner gets out of your way, and you can go on
1703 about your business. Later on, when you decide to actually work on
1704 that ``Memorize Planner keybindings'' task, you will be able to
1705 follow the hyperlink from that task on your day or project page
1706 directly to the relevant node in the Planner info file!
1708 By default, @command{M-x planner-create-task-from-buffer} creates
1709 medium-priority tasks, marked with the letter @samp{B}. But you can
1710 specify a particular priority or change the default (@pxref{Task
1713 You don't have to use @command{planner-create-task-from-buffer} to
1714 create tasks. You can also create new tasks manually by typing them
1715 directly on your day or project page in the format Planner expects. You
1716 can even still create hyperlinks by using Muse formatting as you
1717 manually type the new task (@pxref{Hyperlinks}). Keep in mind also that
1718 tasks do not have to be linked to any other page.
1720 For convenience, @command{planner-create-task-from-buffer} is bound to
1721 @kbd{C-c C-t} in Planner buffers. You can bind
1722 @command{planner-create-task-buffer} to a shortcut key. See the
1723 manual for your Emacs distribution to find out more about keybinding.
1725 @defun planner-create-task-from-buffer title date plan-page
1726 Create a new task named @var{title} on @var{date} based on the current
1729 With a prefix, associate the task with the current planner page. If
1730 you create a task on a date page, you will be prompted for a plan
1731 page. If you create a task on a plan page, you will be prompted for a
1732 day page. If nil is specified, the task is created only on the
1735 See @code{planner-create-task} for more information.
1737 The new task is created at the top or bottom of the first block of
1738 tasks on the scheduled day page (if any), depending on the value of
1739 @code{planner-add-task-at-end-flag}.
1742 @defun planner-create-task title date annotation plan-page
1743 Create a new task named @var{title} based on the current Wiki page.
1744 If @var{date} is non-nil, makes a daily entry on @var{date}, else
1745 makes an entry in today's planner page. It's assumed that the current
1746 Wiki page is the page you're using to plan an activity. Any time
1747 accrued to this task will be applied to that page's name in the
1748 timelog file, assuming you use timeclock (@pxref{Time Intervals, , ,
1749 Emacs, GNU Emacs Manual}). If @var{annotation} is non-nil, it will be
1750 used for the page annotation. If @var{plan-page} is non-nil, the task
1751 is associated with the given page.
1753 With a prefix, associate the task with the current planner page. If
1754 you create a task on a date page, you will be prompted for a plan
1755 page. If you create a task on a plan page, you will be prompted for a
1756 day page. If nil is specified, the task is created only on the
1759 You probably want to call @code{planner-create-task-from-buffer}
1762 The new task is created at the top or bottom of the first block of
1763 tasks on the scheduled day page (if any), depending on the value of
1764 @code{planner-add-task-at-end-flag}.
1767 @node Task Priorities, Task IDs, Creating a Task, Creating New Tasks
1768 @comment node-name, next, previous, up
1769 @subsubsection Task Priorities
1771 You can set the priority of a task when you create it, rather than
1772 waiting to adjust it after the fact. In order to do this, call the
1773 function corresponding to the priority you want. You probably want to
1774 bind these functions to some keys if you intend to use them much.
1777 @item @code{planner-create-high-priority-task-from-buffer}
1778 creates a task with priority @samp{A}.
1780 @item @code{planner-create-medium-priority-task-from-buffer}
1781 creates a task with priority @samp{B}.
1783 @item @code{planner-create-low-priority-task-from-buffer}
1784 creates a task with priority @samp{C}.
1787 Or, you can change the default priority of
1788 @command{planner-create-task-from-buffer} by customizing
1789 @var{planner-default-task-priority}.
1791 You can actually use just one general priority, but using more than
1792 one color-codes your tasks and gives you a better overview of your
1796 @node Task IDs, Cyclic Tasks, Task Priorities, Creating New Tasks
1797 @comment node-name, next, previous, up
1798 @subsubsection Task IDs
1799 @cindex @file{planner-id.el}, using
1802 After loading @file{planner.el}, make sure that @file{planner-id.el} is
1803 in your load path and add this to your @file{.emacs} (or @file{_emacs}):
1806 (require 'planner-id)
1809 This module modifies the behavior of @file{planner.el}, adding global
1810 task IDs so that tasks can be edited and updated. Planner IDs are of
1811 the form @samp{@{@{Identifier:Number@}@}}.
1815 @defopt planner-id-add-task-id-flag
1816 Non-nil means automatically add global task IDs to newly-created
1817 tasks. If nil, use @command{planner-id-add-task-id} to add IDs to
1818 existing tasks, or @command{planner-id-add-task-id-to-all} to add to
1819 all tasks on the current page.
1822 @defopt planner-id-update-automatically
1823 Non-nil means automatically update linked tasks whenever a page is
1824 saved. If nil, use @command{planner-update-task} to update the linked
1825 task. By default, linked tasks are automatically updated.
1828 @defopt planner-id-tracking-file
1829 File that contains ID tracking data. This file is automatically
1833 @subheading Functions
1835 The following interactive functions are defined in @file{planner-id.el}:
1837 @defun planner-id-jump-to-linked-task &optional info
1838 Display the linked task page. If @var{info} is specified, follow that
1842 @defun planner-id-add-task
1843 Add a task ID for the current task if it does not have one
1844 yet. Update the linked task page, if any.
1847 @defun planner-id-update-tasks-on-page &optional force
1848 Update all tasks on this page. Completed or cancelled tasks are not
1849 updated. This can be added to @code{write-file-functions}. If
1850 @var{force} is non-nil, completed and cancelled tasks are also
1854 @defun planner-id-add-task-id-to-all
1855 Add a task ID for all the tasks on the page. Update the linked page,
1859 @defun planner-id-search-id id
1860 Search for all occurrences of @var{id}.
1863 @defun planner-id-follow-id-at-point
1864 Display a list of all pages containing the ID at point.
1867 @defun planner-id-follow-id-at-mouse event
1868 Display a list of all pages containing the ID at mouse. @var{event} is
1872 @node Cyclic Tasks, Task Detail, Task IDs, Creating New Tasks
1873 @comment node-name, next, previous, up
1874 @subsubsection Cyclic Tasks
1875 @cindex @file{planner-cyclic.el}, using
1876 @cindex tasks, cyclic
1877 @cindex cyclic tasks
1878 @cindex recurring tasks
1880 If there are tasks that you have to do regularly, you can have Planner
1881 schedule those tasks automatically.
1883 Make sure that @file{planner-cyclic.el} is in your load path and add
1884 this to your @file{.emacs} (or @file{_emacs}):
1887 (require 'planner-cyclic)
1890 Create a diary file named @file{~/.diary.cyclic-tasks}
1891 (or the value of @code{planner-cyclic-diary-file}). Here is an example:
1894 Tuesday #B0 _ Study Japanese
1895 Friday #B0 _ Study Japanese (JapaneseStudies)
1898 The first will be a plain task, the second will be linked. The first
1899 line will automatically create its task every Tuesday, while the
1900 second will create it every Friday.
1902 You can schedule tasks in a variety of ways. This module uses the same
1903 syntax for specifying when tasks will be scheduled as the Emacs diary
1904 uses for appointments and events. See @ref{Date Formats, the GNU Emacs
1905 Manual, Date Formats,emacs, the GNU Emacs Manual}, and @ref{Sexp Diary
1906 Entries, the GNU Emacs Lisp Reference Manual, Sexp Diary
1907 Entries,elisp, the GNU Emacs Lisp Reference Manual}, for a full
1908 description of the possibilities.
1910 By default, planner-cyclic creates multiple tasks if you let tasks build
1911 up (that is, the next Tuesday rolls around and you @emph{still} haven't
1912 marked the task as done.) To turn off this behavior:
1915 (setq planner-cyclic-diary-nag nil)
1918 @subheading Functions
1920 @file{planner-cyclic-diary} includes the following interactive
1923 @defun planner-cyclic-create-tasks-maybe
1924 Maybe create cyclic tasks. This will only create tasks for future
1928 @node Task Detail, Deadlines, Cyclic Tasks, Creating New Tasks
1929 @comment node-name, next, previous, up
1930 @subsubsection Task Detail
1933 You may find your planner pages getting very full, so that you want to
1934 have one broad task entry be linked to a more specific list of
1935 sub-tasks. Or, maybe you want to have a number of notes linked to a
1938 @cindex tasks, meta-
1942 This can be done with targets. You can have a task that is really a
1946 #A1 _ Do things in RevelleLog#13 @{@{Tasks:101@}@} (RevelleLog)
1949 @samp{RevelleLog#13} could then be a list of sub-tasks in the form of
1950 a note, or any kind of note.
1952 Or, instead of pointing to a particular note on @samp{RevelleLog}, you
1953 could have the whole page be tasks that you enter in manually, without
1954 linking them to another page. You can just type them in like this:
1957 #A1 _ First specific thing to do
1960 This way, the tasks will only appear on this specific project page,
1961 and not on any daily page, so you only see them when you want to look
1962 up all of the specific tasks associated with @samp{#A1 _ Do things in
1963 RevelleLog @{@{Tasks:101@}@} (RevelleLog)}.
1965 As you can see, the ability to manually enter tasks is one of
1966 Planner's nicest features. It allows you to create tasks that are
1967 not assigned to a specific date (by manually entering them on a
1968 project page with no date) or to a specific project (by manually
1969 entering them on a day page with no project). Yet as long as you enter
1970 them using the syntax it understands, Planner will continue to
1971 recognize them as tasks.
1973 Another way to have a task not be connected to a particular date is to
1974 do @kbd{C-c C-c} (@code{planner-copy-or-move-task}) and specify
1975 @samp{nil} when asked for the date.
1977 If you would like to see a list of all of your unfinished tasks, do
1978 @kbd{M-x planner-list-unfinished-tasks}. This function only checks
1979 day plan pages, not project pages.
1981 @node Deadlines, , Task Detail, Creating New Tasks
1982 @comment node-name, next, previous, up
1983 @subsubsection Deadlines
1984 @cindex tasks, deadlines for
1985 @cindex deadlines, task
1986 @cindex @file{planner-deadline.el}, using
1988 You can use @file{planner-deadline.el} to automatically recalculate
1989 days to a deadline by adding @code{(require 'planner-deadline)} to
1990 your @file{~/.emacs}. With the default setup, make your tasks of the
1994 #A0 _ Some task @{@{Deadline: 2004.09.12@}@}
1997 (Note: There must be at least one space after the colon.)
1999 After you run @code{planner-deadline-update} to update task descriptions,
2000 the task will be of the form
2003 #A0 _ Some task @{@{Deadline: 2004.09.12 - 2 days@}@}
2008 @defopt planner-deadline-regexp
2009 Regular expression for deadline data.
2010 The special deadline string should be regexp group 1. The
2011 date (YYYY.MM.DD) should be regexp group 2.
2014 @subheading Functions
2016 @defun planner-deadline-update
2017 Replace the text for all tasks with deadlines. Deadlines are of the
2018 form @samp{@{@{Deadline: YYYY.MM.DD@}@}} by default.
2021 @defun planner-deadline-change &optional date
2022 Change the deadline of current task to @var{date}. If @var{date} is nil,
2026 @node Organizing Your Tasks, Task Reports and Overviews, Creating New Tasks, More about Tasks
2027 @comment node-name, next, previous, up
2028 @subsection Organizing Your Tasks
2029 @cindex tasks, organizing
2032 Okay, now that you've gotten the hang of creating tasks, you're probably
2033 facing a really long list of things to do. How can you organize them so
2034 that they don't overwhelm you? Planner gives you a number of strategies
2035 for dealing with large numbers of tasks.
2038 @item Arrange your tasks in the rough order you're going to do them.
2039 @item Use #A, #B and #C task priorities to differentiate between
2040 high-priority, normal and low-priority tasks.
2041 @item Schedule your tasks onto different days.
2042 @item Group your tasks into plan pages.
2043 @item Don't schedule all your tasks.
2048 @item @emph{Task order}
2050 To remind yourself to do tasks in a certain order, simply edit the
2051 lines so that they're in the order you want. You can use normal
2052 editing commands like kill, yank and transpose-line to reorder the
2053 tasks, or use @key{M-p} (@code{planner-raise-task}) and @key{M-n}
2054 (@code{planner-lower-task}) to rearrange the tasks.
2056 @item @emph{Task priorities}
2058 By default, tasks are created with medium priority (@samp{#B}). You
2059 can make a task high-priority (@samp{#A}) or low-priority (@samp{#C})
2060 by manually editing the task and calling M-x planner-update-task to
2061 update the linked page. Alternatively, you can use @key{C-M-p}
2062 (@code{planner-raise-task-priority}) and @key{C-M-n}
2063 (@code{planner-lower-task-priority}) to modify the task and update the
2066 You can edit the priority of a task using @kbd{M-x
2067 planner-edit-task-priority}, or manually edit it and call @kbd{M-x
2068 planner-update-task} to update tasks on the linked page.
2070 @item @emph{Schedule your tasks on different days}
2072 You don't have to do everything today. Is this a task you would rather
2073 do tomorrow? Schedule it for then instead. You can specify @samp{+n}
2074 or @samp{-n} whenever you are asked for a date, where @var{n} is the
2075 number of days before or after the current file's date or today.
2076 Don't over-procrastinate things, though!
2078 @item @emph{Plan pages}
2080 Plan pages let you group related tasks and notes together for easy
2081 reference. For example, you could have a plan page for each major
2082 project or goal in your life, like @samp{GoodHealth} or
2083 @samp{FurtherStudies}.
2085 Although plan pages start by grouping everything under a @samp{*
2086 Tasks} header, you can organize your plan pages in different ways. For
2087 example, you can separate groups of tasks with blank lines, and
2088 Planner will sort tasks within each group.
2090 @item @emph{Tasks without dates}
2092 Plan pages also allow you to have undated tasks or tasks with no
2093 particular deadlines. This keeps your daily task list small and
2094 manageable while making it easier for you to find things to do if you
2095 have free time. Make sure you check your plan pages regularly so that
2096 you don't completely forget about them.
2098 For automated scheduling of the next task on a plan page after you
2099 complete a task, see the section in
2100 @uref{http://sacha.free.net.ph/notebook/emacs/planner-config.el} named
2101 ``Schedule next undated task from same project''.
2107 * Multiple Projects::
2110 * Carrying Over Unfinished Tasks::
2112 * Task Ranks:: planner-rank.el
2113 * Grouping Tasks:: planner-trunk.el
2116 @node Multiple Projects, Viewing Tasks, Organizing Your Tasks, Organizing Your Tasks
2117 @comment node-name, next, previous, up
2118 @subsubsection Associating Tasks with Multiple Projects
2119 @cindex multiple projects
2120 @cindex @file{planner-multi.el}, using
2122 You can use @file{planner-multi.el} to associate a task with more than
2123 one project. That way, you can easily keep GTD-style context lists as
2124 well as project-related lists.
2126 To use multiple projects, add the following to your @samp{~/.emacs}:
2129 (require 'planner-multi)
2132 Under GNU Emacs, you can specify multiple projects by separating them
2133 with a single space. For example, you can specify @kbd{planner doc}
2134 when creating a task to associate the task with those two projects.
2136 Under XEmacs, you can specify multiple projects by typing @kbd{RET}
2137 after each entry and terminating the list with another @kbd{RET}. For
2138 example, to specify @kbd{planner} and @kbd{doc}, you would type
2139 @kbd{planner RET doc RET RET} at the prompt.
2141 If you want to see an overview of all of your tasks as well as
2142 project- or context-specific lists, you can set
2143 @code{planner-multi-copy-tasks-to-page} to your overview page(s). For
2144 example, set it to @samp{TaskPool} to be able to see an overview of
2145 all of your unfinished tasks. You can also set this to multiple pages
2146 such as @samp{[[TasksByProject][p]] [[TasksByContext][c]]} and use
2147 @file{planner-trunk.el} to sort and organize tasks for easy reference.
2148 (@pxref{Grouping Tasks})
2152 @defopt planner-multi-copy-tasks-to-page
2153 Automatically copy newly-created tasks to the specified page.
2156 By default, tasks are removed from
2157 @code{planner-multi-copy-tasks-to-page} when you call
2158 @code{planner-task-done} or @code{planner-task-cancelled}. If you
2159 prefer to keep a copy of the task, remove
2160 @code{planner-multi-remove-task-from-pool} from
2161 @code{planner-mark-task-hook}.
2163 If you want to use a different separator instead of spaces, customize
2164 the @code{planner-multi-separator} variable.
2166 @defopt planner-multi-separator
2167 String that separates multiple page references.
2169 For best results, this should be something recognized by
2170 @code{muse-link-at-point} so that links are highlighted
2174 @node Viewing Tasks, Modifying Tasks, Multiple Projects, Organizing Your Tasks
2175 @comment node-name, next, previous, up
2176 @subsubsection Viewing tasks
2177 @cindex tasks, viewing
2179 Review the tasks scheduled for today by typing @kbd{M-x
2180 planner-goto-today}. If you created the task from the previous
2181 section in this tutorial, you should see a line that looks like
2184 #A _ Learn how to change a task's status from Tasks (TaskPool)
2187 If you have @code{planner-use-task-numbers} set to non-nil, you will see
2188 something like the following instead.
2191 #A0 _ Learn how to change a task's status from Tasks (TaskPool)
2194 From left to right, these are what the symbols mean:
2197 @item @samp{A} - Priority. A (high)
2199 @samp{0} - Priority number. It is calculated whenever you save the file
2200 or call @command{planner-renumber-tasks}, provided that
2201 @code{planner-use-task-numbers} is non-nil. Tasks are numbered in
2202 ascending order according to priorities.
2203 @item @samp{_} - Status. _ (unfinished)
2206 If you click on @samp{Tasks} or press @key{RET} while your cursor is
2207 in the link, Emacs will display the previous info page.
2209 If you select @samp{TaskPool}, Emacs will display the @samp{TaskPool}
2210 plan page. Plan pages organize your tasks and notes about a project
2213 @subheading Functions
2215 You can use @command{planner-seek-next-unfinished-task} to move to the
2216 next unfinished task on the current page.
2218 @defun planner-list-tasks-with-status status &optional pages
2219 Display all tasks that match the STATUS regular expression on all day
2220 pages. The PAGES argument limits the pages to be checked in this
2224 @item @code{t}: check all pages
2225 @item regexp: search all pages whose filenames match the regexp
2226 @item list of page names: limit to those pages
2227 @item alist of page/filenames: limit to those pages
2230 Called interactively, this function will search day pages by
2231 default. You can specify the start and end dates or leave them as
2232 nil to search all days. Calling this function with an interactive
2233 prefix will prompt for a regular expression to limit pages.
2234 Specify @samp{.} or leave this blank to include all pages.
2236 This function could take a long time.
2239 @defun planner-list-unfinished-tasks &optional pages
2240 Display all unfinished tasks. @var{pages} follows
2241 planner-list-tasks-with-status.
2244 @defun planner-jump-to-linked-task task-info
2245 Display the task page linked to by the current task or
2249 @node Modifying Tasks, Carrying Over Unfinished Tasks, Viewing Tasks, Organizing Your Tasks
2250 @comment node-name, next, previous, up
2251 @subsubsection Modifying Tasks
2252 @cindex tasks, modifying
2253 @cindex tasks, editing
2255 To select a task, move your cursor to the line containing the task.
2257 Change a task's priority (@samp{A}, @samp{B} or @samp{C}) by editing
2258 the line. @samp{#A} tasks are important. @samp{#B} are medium
2259 priority. @samp{#C} are low priority. Whenever you save the file or
2260 call @kbd{M-x planner-fix-tasks}, tasks are sorted and numbered
2261 according to priority and status.
2263 Change a task's status by calling one of the following functions:
2266 @item planner-task-in-progress @samp{o} (@kbd{C-c C-z})
2267 @item planner-task-done @samp{X} (@kbd{C-c C-x})
2268 @item planner-task-cancelled @samp{C} (@kbd{C-c C-S-x})
2269 @item planner-task-delegated @samp{D}
2270 @item planner-task-pending @samp{P}
2271 @item planner-task-open @samp{_}
2274 After changing the status using a function, look at the
2275 @samp{TaskPool} plan page. The task is also updated on the linked
2276 page. If you changed the task status manually by replacing the status
2277 with another character, you will need to call
2278 @command{planner-update-task} to update the linked page.
2280 To reschedule a task, call @command{planner-copy-or-move-task} (@kbd{C-c
2281 C-c}) and choose a new date. You can mark a region and type @kbd{M-x
2282 planner-copy-or-move-region} to reschedule all the contained tasks to a
2283 different date. Enter @samp{nil} for the date if you don't want the
2284 task or group of tasks to appear on any date page at all anymore. This
2285 is a good way to ``de-schedule'' a task for the time being, but still
2286 keep it linked to a plan page for possible future scheduling.
2288 To change the plan page associated with a task, call
2289 @command{planner-replan-task}. Enter @samp{nil} for the plan page if
2290 you don't want the task to appear on any plan page anymore. If you
2291 precede the command with a prefix argument, the text of the original
2292 plan page will appear in the prompt for easy editing.
2294 Since the same task may exist on two or more pages, such as a date page
2295 and a plan page, it is dangerous to edit the description of the task by
2296 hand. You should not do it unless you want to make the exact same
2297 changes on all its linked pages.
2299 Instead of doing this by hand, you should use
2300 @command{planner-edit-task-description}. This will prompt you for the
2301 changes to the task description and then update all the other pages to
2302 which the task is linked. Or, you can just use
2303 @command{planner-delete-task} to remove the task from both pages, and
2304 then create it again with the new desired description.
2306 To remind yourself to do tasks in a certain order, simply edit the
2307 lines so that they're in the order you want.
2308 @command{planner-raise-task} and @command{planner-lower-task} update
2309 the priorities on linked pages automatically. You can organize tasks
2310 into groups by putting a blank line between groups of tasks.
2311 Planner will maintain the groupings and only sort the tasks within
2314 @subheading Functions
2316 @defun planner-replan-task page-name
2317 Change or assign the plan page for the current task. @var{page-name}
2318 is the new plan page for the task. Use
2319 @code{planner-copy-or-move-task} if you want to change the date. With a
2320 prefix, provide the current link text for editing.
2323 @defun planner-raise-task-priority
2324 Change a low-priority task to a medium-priority task and a
2325 medium-priority task to a high-priority task (C to B to A).
2328 @defun planner-lower-task-priority
2329 Change a high-priority task to a medium-priority task and a
2330 medium-priority task to a low-priority task (A to B to C).
2333 @defun planner-raise-task arg
2334 Move a task up @var{arg} steps. By default, @var{arg} is 1.
2337 @defun planner-lower-task arg
2338 Move a task down @var{arg} steps. By default, @var{arg} is 1.
2341 @defun planner-edit-task-description description
2342 Change the description of the current task, updating the linked page
2346 @defun planner-delete-task
2347 Delete this task from the current page and the linked page.
2350 @defun planner-update-task
2351 Update the current task's priority and status on the linked page.
2352 Tasks are considered the same if they have the same description.
2353 This function allows you to force a task to be recreated if it
2354 disappeared from the associated page.
2356 Note that the text of the task must not change. If you want to be able
2357 to update the task description, see @code{planner-edit-task-description}
2358 or @file{planner-id.el}.
2361 See @command{planner-install-extra-task-keybindings} for additional
2362 task-related shortcuts.
2364 @node Carrying Over Unfinished Tasks, Task Numbering, Modifying Tasks, Organizing Your Tasks
2365 @comment node-name, next, previous, up
2366 @subsubsection Carrying Over Unfinished Tasks
2367 @cindex tasks, carrying over
2369 Sometimes you won't be able to cross off all the tasks on your list.
2370 Planner makes it easy for you to keep track of things you still have
2371 to do by automatically rescheduling unfinished tasks from the past few
2372 days. By default, the @command{plan} command searches for unfinished
2373 tasks from the last three days and reschedules them onto today. If you
2374 open Planner every day, this should cover weekends easily.
2376 It's a good idea to start Planner whenever you start Emacs. That way,
2377 Planner can help remind you about today's tasks, appointments, and other
2378 things. To automatically start Planner whenever you start up Emacs, add
2379 the following code to the end of your @file{~/.emacs}:
2385 Now, every time you start Emacs (which should be more or less once a
2386 day), you'll see today's page. If you don't finish all the tasks today,
2387 you'll see them again tomorrow.
2389 It's a good idea to start Planner every time you start Emacs so that
2390 you get reminded about your task list. If you prefer to start Planner
2391 manually, remember to call @kbd{M-x plan} every so often to make sure
2392 that you don't forget any unfinished tasks. Safe in the knowledge that
2393 Planner tasks won't slip through the cracks (unlike little slips of
2394 paper that will invariably get mislaid), you can then get on with the
2397 If your increased productivity with Planner leads to a well-deserved
2398 two-week vacation, then you'll need to tell Planner to search more days
2399 for unfinished tasks. By using @kbd{M-x plan}, you can automatically
2400 bring forward tasks over a given number of days or even scan all the
2401 days since time immemorial. @kbd{C-u 15 M-x plan} reschedules all
2402 unfinished tasks from the last 15 days. @kbd{C-u -1 M-x plan} checks all
2403 of your past day pages for unfinished tasks.
2405 Like everything else in Planner, you can adapt @kbd{M-x plan} to your
2406 particular way of life. For example, if you find yourself starting up
2407 Emacs and Planner every day--including weekends--because it's just so
2408 much fun, you can set the @code{planner-carry-tasks-forward} to 1.
2409 This can make your Emacs startup marginally faster. On the other hand,
2410 if you normally start Emacs once a week, you can set it to 7 or 8. If
2411 you're worried about tasks dropping off your radar, you can set it to
2412 0. You can set the value of @var{planner-carry-tasks-forward} either
2413 with @key{M-x customize-variable RET planner-carry-tasks-forward RET},
2414 or by putting @code{(setq planner-carry-tasks-forward 3)} (replacing
2415 @code{3} with the value appropriate for what you want) in your
2416 @file{~/.emacs} file.
2418 On the other hand, you might prefer to reschedule tasks yourself. If
2419 you set @code{planner-carry-tasks-forward} to @code{nil}, then
2420 @command{M-x plan} and @code{(plan)} will bring you to the most recent
2421 page with unfinished tasks if there is no page for today. You can then
2422 use @command{planner-copy-or-move-task} and
2423 @command{planner-copy-or-move-region} to reschedule tasks. This is
2424 probably more hassle than it's worth, though, so let Planner take care
2429 @defopt planner-carry-tasks-forward
2430 If non-nil, carry unfinished tasks forward automatically.
2431 If a positive integer, scan that number of days in the past.
2432 If 0, scan all days for unfinished tasks.
2433 If t, scan one day in the past (old behavior).
2434 If nil, do not carry unfinished tasks forward.
2437 @subheading Functions
2439 @defun plan &optional force-days
2440 Start your planning for the day, carrying unfinished tasks forward.
2442 If @var{force-days} is a positive integer, search that many days in the
2443 past for unfinished tasks.
2444 If @var{force-days} is @code{0} or @code{t}, scan all days.
2445 If @var{force-days} is @code{nil}, use the value of
2446 @code{planner-carry-tasks-forward} instead, except t means scan only
2451 @defun planner-copy-or-move-task date force
2452 Reschedule the task for @var{date}. If @var{force} is non-nil, the
2453 task is moved regardless of status. It also works for creating tasks
2454 from a Note. Use @code{planner-replan-task} if you want to change the
2455 plan page in order to get better completion.
2458 @defun planner-copy-or-move-region beg end date muffle-errors
2459 Move all tasks from @var{beg} to @var{end} to @var{date}.
2460 @code{planner-copy-or-move-region} will copy or move all tasks from
2461 the line containing @var{beg} to the line just before @var{end}. If
2462 @var{muffle-errors} is non-nil, no errors will be reported.
2465 @node Task Numbering, Task Ranks, Carrying Over Unfinished Tasks, Organizing Your Tasks
2466 @comment node-name, next, previous, up
2467 @subsubsection Task Numbering
2469 By default, tasks are numbered according to their position on the
2470 page. Task numbers allow you to refer to tasks using Muse links.
2471 For example, the @samp{#A1} task in @file{2004.08.16} can be referred to
2472 as @samp{2004.08.16#A1}.
2474 Note that task numbers change every time you re-sort and re-number tasks
2475 with @code{planner-fix-tasks}. As a result, they are only reliable for
2476 references to past tasks.
2478 If you find yourself not using this functionality, you can turn off task
2479 numbers by using the following option.
2483 @defopt planner-use-task-numbers
2484 Non-nil means use task numbers when creating tasks. This allows you
2485 to refer to past tasks if your tasks are numbered appropriately.
2486 If you set this to nil, you can save space in your plan files.
2489 @node Task Ranks, Grouping Tasks, Task Numbering, Organizing Your Tasks
2490 @comment node-name, next, previous, up
2491 @subsubsection Task Ranks
2492 @cindex ranking tasks
2493 @cindex tasks, ranking
2494 @cindex @file{planner-rank.el}, using
2496 @file{planner-rank.el} models Franklin Covey's Urgency and Importance
2497 principle. When you think about a task, there are two aspects in
2498 consideration: Urgency and Importance. You may want to do the most
2499 urgent things first, like answering an email, or you may want to do
2500 the most important things first, like reading this manual. Or much
2501 better, balance Urgency and Importance and decide what to do.
2503 @file{planner-rank.el} can help you balance.
2505 Urgency and Importance are both measured by scores from 0-9. The
2506 higher the score, the more you want to do it first. 9 stands for ``I
2507 should have done this'' and 0 stands for ``I can forget this''.
2509 If you are using the planner @ref{Deadlines} feature, the Urgency
2510 score is automatically calculated from how many days are left to meet
2511 the deadline. By default, it will score 9 if the task is overdue and 0
2512 if the deadline is years away. Please refer to the docstring of
2513 @code{planner-rank-deadline-urgency-map-list} for detail.
2515 The task rank is calculated from Urgency and Importance scores. As
2516 different people balance urgency and importance differently, a number
2517 of @code{planner-rank-calculate-rank-*} functions are provided. The
2518 algorithms vary from a simple average to something like a weighted
2519 root mean square deviation.
2521 The aggressive versions of these functions
2522 (@code{planner-rank-calculate-rank-*-aggressive}) will make sure if
2523 one of Urgency and Importance is high, the resulting rank will be high
2524 as well. @code{planner-rank-calculate-rank-weighted-*} functions weigh
2525 the Urgency and Important scores depending on
2526 @code{planner-rank-importance-vs-urgency-factor}.
2528 Call @code{planner-rank-test-algorithm} on each of the functions and
2529 check the result tables to see which one you like most, and set it to
2530 @code{planner-rank-rank-calculate-function}. Alternatively, accept the
2531 defaults and tweak them when you get a better feel for ranking.
2533 Once the Rank is calculated, the @ref{Task Priorities} will be
2534 automatically reset. If the Rank is greater than or equal to
2535 @code{planner-rank-priority-A-valve}, the task priority will be
2536 @samp{A}, if the Rank is between @code{planner-rank-priority-A-valve}
2537 and @code{planner-rank-priority-B-valve}, the priority will be @samp{B},
2538 else it will be @samp{C}.
2540 After setting the task importance and deadline, you can leave it as
2541 is. As the deadline approaches, the task priority will automatically
2542 be raised and the task re-colored to catch your eyes.
2544 If you are using @code{planner-sort-tasks} (see @pxref{Making Files
2545 Pretty}), you can set @code{planner-sort-tasks-key-function} to one of
2546 @code{planner-sort-tasks-by-rank},
2547 @code{planner-sort-tasks-by-importance}, and
2548 @code{planner-sort-tasks-by-urgency}.
2552 @defopt planner-rank-change-hook
2553 Functions to run after @code{planner-rank-change}.
2556 @defopt planner-rank-priority-A-valve
2557 Tasks with rank greater than or equal to this value will be set to
2561 @defopt planner-rank-priority-B-valve
2562 Tasks with rank greater than or equal to this value and less than
2563 @code{planner-rank-priority-A-valve} will be set to priority
2564 @samp{B}. Tasks with rank less than this value will be set to priority
2568 @defopt planner-rank-deadline-urgency-map-list
2569 Defines how to calculate the Urgency score according to how many days
2570 are left to meet the deadline.
2573 @defopt planner-rank-default-importance
2574 Default importance value for newly added rank.
2577 @defopt planner-rank-default-urgency
2578 Default urgency value for newly added rank.
2581 @defopt planner-rank-importance-vs-urgency-factor
2582 How much do you think importance is more ``important'' than urgency.
2583 This will be used in @code{planner-rank-calculate-rank-weighted-*}
2587 @defopt planner-rank-rank-calculate-function
2588 Define the function called to calculate rank.
2591 @subheading Functions
2593 @defun planner-rank-change &optional importance urgency
2594 Set the Importance and Urgency of the current task.
2597 @defun planner-rank-update-current-task
2598 Recalculate rank for the current task.
2601 @defun planner-rank-update-all
2602 Recalculate rank for all tasks in the current page
2605 @defun planner-rank-update-all
2606 Recalculate rank for all tasks in the current page
2609 @node Grouping Tasks, , Task Ranks, Organizing Your Tasks
2610 @comment node-name, next, previous, up
2611 @subsubsection Grouping Tasks with planner-trunk.el
2612 @cindex grouping tasks
2613 @cindex tasks, grouping
2614 @cindex @file{planner-trunk.el}, using
2616 @file{planner-trunk.el} helps you automatically group tasks according
2617 to a set of rules. It sorts and splits your tasks, adding a blank line
2618 between groups of tasks. For example, if today's page looks like this:
2623 #B _ Buy milk (GroceryShopping)
2624 #B _ Learn how to use planner-trunk (PlannerMode)
2625 #B _ Buy a notebook (Bookstore)
2626 #B _ Buy cereal (GroceryShopping)
2627 #B _ Set up my own planner-trunk rules (PlannerMode)
2628 #B _ Customize my stylesheet (MuseMode)
2629 #B _ Go for a health checkup (BetterHealth)
2633 then you might want to group the tasks into: planner and muse,
2634 shopping list, and other items. If you set up the appropriate rules by
2635 customizing @code{planner-trunk-rule-list}, @file{planner-trunk.el}
2636 can automatically rewrite that section line this:
2641 #B _ Learn how to use planner-trunk (PlannerMode)
2642 #B _ Set up my own planner-trunk rules (PlannerMode)
2643 #B _ Customize my stylesheet (MuseMode)
2645 #B _ Buy milk (GroceryShopping)
2646 #B _ Buy a notebook (BookstoreShopping)
2647 #B _ Buy cereal (GroceryShopping)
2649 #B _ Go for a health checkup
2653 In this case, you would set @code{planner-trunk-rule-list}
2654 to @code{(("." nil ("PlannerMode\\|MuseMode" "Shopping")))}.
2656 You can load @file{planner-trunk} with @kbd{M-x load-library RET
2657 planner-trunk RET} or add @code{(require 'planner-trunk)}. If you're
2658 not yet comfortable with Emacs Lisp, you can use @kbd{M-x
2659 customize-variable RET planner-trunk-rule-list RET} to edit this rule
2660 using an easy-to-use interface.
2662 WARNING: Do not keep non-task information in the Tasks section.
2663 planner-trunk will delete @strong{all} non-task lines from the Tasks
2664 section of your plan page in the process of grouping the tasks.
2666 After you set up @code{planner-trunk-rule-list}, use @command{M-x
2667 planner-trunk-tasks} to try out your rules until you're satistfied.
2669 If you want to do this automatically, you can use @code{(add-hook
2670 'planner-mode-hook 'planner-trunk-tasks)} to trigger it automatically
2671 whenever you open a Planner page.
2673 @node Task Reports and Overviews, , Organizing Your Tasks, More about Tasks
2674 @subsection Task Reports and Overviews
2675 @cindex task reports
2676 @cindex task overviews
2677 @cindex reports, task
2678 @cindex overviews, task
2679 @cindex reports, accomplishment
2680 @cindex tasks, overview of
2682 Planner provides a number of different ways to generate different
2683 presentations of your tasks.
2686 * Accomplishments:: planner-accomplishments.el
2687 * Status Reports:: planner-report.el
2688 * Task Overviews:: planner-tasks-overview.el
2690 * planner-registry:: Keep track of annotations
2691 * planner-zoom:: View and navigate tasks by time period
2694 @node Accomplishments, Status Reports, Task Reports and Overviews, Task Reports and Overviews
2695 @comment node-name, next, previous, up
2696 @subsubsection Generating Daily Accomplishment Reports
2697 @cindex reports, accomplishment
2698 @cindex @file{planner-accomplishments.el}, using
2699 @cindex tasks, overview of
2700 @cindex task reports
2701 @cindex reports, task
2702 @cindex overviews, task
2703 @cindex task overviews
2705 You can use @file{planner-accomplishments.el} to get a summary of your
2706 task activity for a particular day. The report is grouped by status
2707 and plan (on day pages) or date (on plan pages). An example report
2711 Link | Unfinished | In progress | Delegated | Completed | Total
2712 nil | 1 | 0 | 0 | 6 | 7
2713 TaskPool | 1 | 1 | 0 | 3 | 5
2714 Planner | 0 | 0 | 1 | 1 | 2
2715 SchoolWork | 0 | 0 | 0 | 1 | 1
2716 Total | 2 | 1 | 1 | 11 | 15
2719 This lets you see how you balance your time between your projects.
2723 There are currently two ways to use @file{planner-accomplishments.el}.
2725 @item Displaying a temporary buffer
2727 You can call @code{planner-accomplishments-show} to display a buffer
2728 containing the current page's accomplishment report.
2730 @item Rewriting sections of your planner
2732 Choose this approach if you want accomplishment reports to be in
2733 their own section and you would like them to be readable in your
2734 plain text files even outside Emacs. Caveat: The accomplishment
2735 section should already exist in your template and will be rewritten
2738 To use, set @code{planner-accomplishments-section} to the name of the
2739 section to rewrite (default: @samp{Accomplishments}). If you want
2740 rewriting to be automatically performed, call
2741 @code{planner-accomplishments-insinuate}. The accomplishments will be
2742 rewritten whenever you save a planner page. If you want rewriting to
2743 be manual, call @code{planner-accomplishments-update}.
2749 @defopt planner-accomplishments-section
2750 Header for the accomplishments section in a plan page.
2751 Used by @code{planner-accomplishments-update}.
2754 @defopt planner-accomplishments-status-display
2755 Alist of status-label maps also defining the order of display.
2756 Used by @code{planner-accomplishments-format-table}.
2759 @subheading Functions
2761 @defun planner-accomplishments-insinuate ()
2762 Automatically call @code{planner-accomplishments-update} when saving
2763 tasks in @code{planner-mode} buffers.
2766 @defun planner-accomplishments-update ()
2767 Rewrite @code{planner-accomplishments-section} with a summary of tasks
2771 @defun planner-accomplishments-show ()
2772 Display a buffer with the current page's accomplishment report.
2775 @node Status Reports, Task Overviews, Accomplishments, Task Reports and Overviews
2776 @comment node-name, next, previous, up
2777 @subsubsection Status Reports
2778 @cindex status reports
2779 @cindex reports, status
2780 @cindex @file{planner-report.el}, using
2782 @file{planner-report.el} creates a status report for a given timespan.
2783 The report itself is just another Planner page in your planner
2784 directory. Once generated, it contains tasks and notes culled from
2785 active project pages. Tasks are only shown if they are incomplete or
2786 were completed within the timespan. Notes are shown if they were
2787 created during the timespan. Tasks and notes are grouped together under
2788 a heading for their corresponding project.
2790 The idea is you have one of these status reports generated periodically
2791 (say, every couple of weeks). Perhaps you use cron to run them
2792 automatically and then mail you a reminder that they've been done. Then
2793 you can edit the page, adding verbiage where it is needed and removing
2794 irrelevant items. This editing process is as easy as editing any other
2795 Planner page. Finally, you can publish the page along with the rest of
2796 your planner using @kbd{M-x muse-project-publish}.
2798 If you use planner-authz.el, you can tell planner-report.el only to
2799 consult project pages that a given list of users
2800 (@var{planner-report-authz}) can access when generating the report. For
2801 example, if you're preparing a status report for your boss, add yourself
2802 and him to @var{planner-report-authz}. The resulting status report will
2803 only contain information the two of you are supposed to have access to,
2804 and the report itself will be similarly restricted.
2806 @subheading Getting started
2808 Add the following to your .emacs file:
2811 (require 'planner-report)
2814 Then you can use the following command to generate a status report:
2817 M-x planner-report-generate
2820 You will be prompted for a beginning and ending date, and then the
2821 status report will be generated. You can then edit it to your liking
2822 and publish it just like you would the rest of your planner.
2826 @defopt planner-report-authz
2827 List of users a status report should be restricted to.
2828 When status reports are generated, only planner pages accessible
2829 by these users will be consulted, and the resulting status report
2830 will be similarly restricted.
2833 @defopt planner-report-pretty-print-plan-pages
2834 If non-nil, pretty print plan pages.
2835 If nil, leave page names as-is.
2836 This requires that @file{muse-wiki.el} be loaded to work properly.
2839 @defopt planner-report-remove-task-numbers
2840 Remove task numbers when generating status reports.
2843 @defopt planner-report-replace-note-numbers
2844 If non-nil, a string with which to replace note numbers when
2845 generating status reports.
2848 @defopt planner-report-unfinished-offset
2849 If non-nil, the offset in days from the current date of
2850 unfinished tasks to include in the status report. If nil,
2851 include all unfinished tasks.
2854 @subheading Functions
2856 @defun planner-report-generate begin end
2857 Generate a status report spanning a period from @var{begin} to @var{end}.
2858 @var{begin} and @var{end} are in the format YYYY.MM.DD.
2861 @node Task Overviews, <tasks> tag, Status Reports, Task Reports and Overviews
2862 @comment node-name, next, previous, up
2863 @subsubsection Seeing an Overview of Tasks
2864 @cindex tasks, overview of
2865 @cindex task reports
2866 @cindex reports, task
2867 @cindex overviews, task
2868 @cindex task overviews
2869 @cindex @file{planner-tasks-overview.el}, using
2871 You can see a list of tasks with @file{planner-tasks-overview.el}.
2872 Seeing how you've scheduled tasks over the next few days can help you
2873 decide when to schedule another task. Table entries will be of the form
2875 @var{date} | @var{link} | @var{priority} @var{status} | @var{task-description}
2877 @subheading Functions
2879 To display the tasks between a set of day pages, use
2881 @defun planner-tasks-overview start end
2882 Display an overview of your tasks from @var{start} to @var{end}. If
2883 @var{start} is nil, start from the very first day page. If @var{end}
2884 is nil, include the very last day page. You can use
2885 @code{planner-expand-name} shortcuts here, like @kbd{+1} or @kbd{-1}.
2886 Pressing @key{RET} at the prompt will use today.
2888 Once in a @code{planner-tasks-overview} buffer, you can use
2889 the keyboard shortcut @key{o} to change the overview period.
2892 You can sort the task display with the following functions:
2894 @defun planner-tasks-overview-sort-by-date
2895 Sort the tasks by date. Keyboard shortcut: @key{1}
2898 @defun planner-tasks-overview-sort-by-plan
2899 Sort the tasks by associated plan page. Keyboard shortcut: @key{2}
2902 @defun planner-tasks-overview-sort-by-priority
2903 Sort the tasks by priority. Keyboard shortcut: @key{3}
2906 @defun planner-tasks-overview-sort-by-status
2907 Sort the tasks by status. Keyboard shortcut: @key{4}
2910 You can jump to linked tasks with
2912 @defun planner-tasks-overview-jump other-window
2913 Display the current task. If a prefix argument is supplied, show the
2914 task in another window. Keyboard shortcut: @key{j}
2917 @defun planner-tasks-overview-jump-other-window
2918 Display the current task in another window. Keyboard shortcut: @kbd{C-u j}
2921 You can view a summary of the tasks in your plan pages with
2923 @defun planner-tasks-overview-show-summary &optional file-list
2924 Count unscheduled, scheduled, and completed tasks for FILE-LIST. If
2925 called with an interactive prefix, prompt for the plan page(s) to
2926 display. Load @file{planner-multi.el} to be able to specify multiple
2932 @key{TAB}, @kbd{SHIFT-TAB} and @key{RET} navigate links in the usual
2935 @node <tasks> tag, planner-registry, Task Overviews, Task Reports and Overviews
2936 @subsubsection <tasks> tag
2938 @cindex task reports
2939 @cindex reports, task
2940 @cindex overviews, task
2941 @cindex task overviews
2942 @cindex tasks, overview of
2944 @samp{<tasks>} is replaced by a report of tasks over all day pages in
2945 published pages (@pxref{Publishing}).
2948 All incomplete tasks
2961 Warning: this function can be slow, as it checks all the day pages!
2963 @node planner-registry, planner-zoom ,<tasks> tag, Task Reports and Overviews
2964 @comment node-name, next, previous, up
2965 @section planner-registry
2966 @cindex @file{planner-registry.el}, using
2968 The @file{planner-registry} module provides a way to keep track of all
2969 the URLs in your projects, and to list them depending on the current
2970 buffer. The URLs are defined in @code{muse-url-protocols} module from
2973 If a URL has been created by @code{planner-create-task-from-buffer},
2974 going to that buffer and calling @code{planner-registry-show} will show
2975 you where Planner put the URL.
2977 @subheading Getting started
2979 To begin using @file{planner-registry}, add the following to your
2980 Planner configuration file.
2983 (require 'planner-registry)
2984 (planner-registry-initialize)
2987 You must put it after the place where Planner has been loaded in your
2990 If you want the registry to be updated each time you save a Planner
2991 file, add the following to your Planner configuration.
2994 (planner-registry-insinuate)
2997 If you don't want to update the registry each time a file is written,
2998 you can do it manually with @code{planner-registry-update}: it will
2999 update the registry for saved Planner/Muse buffers only.
3001 @file{planner-registry} does not define any keybindings by default. Its
3002 most useful interactive function is @code{planner-registry-show}.
3004 @subheading Example usage
3006 Say for example that you created a task from an e-mail. Go to that
3007 e-mail and call @code{planner-registry-show}: it will open a new buffer
3008 displaying the files (in a muse links format) where a link to this
3009 e-mail has been added.
3013 @file{planner-registry} defines the following options.
3015 @defopt planner-registry-file
3016 The file where @file{planner-registry} stores its URL registry.
3019 @defopt planner-registry-min-keyword-size
3020 The minimum size for keywords.
3023 @defopt planner-registry-max-keyword-size
3024 The maximum size for keywords.
3027 @defopt planner-registry-max-number-of-keywords
3028 The maximum number of keywords.
3031 @defopt planner-registry-ignore-keywords
3032 A list of keywords to ignore.
3035 @defopt planner-registry-show-level
3036 Level used by the @code{planner-registry-show} function.
3037 0 means that this function shows only exact matches.
3038 1 means that this function also shows descriptive matches.
3039 2 (or more) means that this function also shows fuzzy matches.
3042 @node planner-zoom, , planner-registry, Task Reports and Overviews
3043 @comment node-name, next, previous, up
3044 @section planner-zoom
3045 @cindex @file{planner-zoom.el}, using
3046 @cindex view, weekly
3047 @cindex view, quarterly
3048 @cindex view, monthly
3049 @cindex view, yearly
3051 When assessing where you stand in relation to the tasks you have set
3052 out for yourself, you might want a way to survey those tasks in groups
3053 divided by time periods, like by the week or by the month. You could
3054 create all of these overview pages by hand, but if you like to have
3055 this kind of overview frequently, you might find manually creating
3056 such pages to be tedious and time consuming.
3058 @file{planner-zoom} is an optional module designed to make it easy to
3059 view your task information grouped by year, quarter, month, week or
3062 To install this module, just load it in your @file{.emacs} (or
3066 (require 'planner-zoom)
3069 This module will recognize planner pages named according to the
3078 @file{2006.Quarter2}
3084 @file{2006.January.Week3}
3091 @subheading Keybindings
3093 This module also adds key bindings that you can use when looking at a
3094 Planner page to easily jump between the different time-period views.
3099 Move to the view corresponding to the time period one step larger than
3100 the current one. For example, it moves from the weekly view to the
3101 monthly view. It calls @code{planner-zoom-iup}.
3104 Move to the view corresponding to the time period one step smaller
3105 than the current one. For example, it moves from the weekly view to
3106 the daily view. It calls @code{planner-zoom-idown}.
3109 Stay in the same time-period view as the current one, but move one
3110 interval earlier. For example, it moves from @file{2006.January.Week3}
3111 to @file{2006.January.Week2}. It calls @code{planner-zoom-iprev}.
3114 Stay in the same time-period view as the current one, but move one
3115 interval later. For example, it moves from @file{2006.January.Week3}
3116 to @file{2006.January.Week4}. It calls @code{planner-zoom-inext}.
3120 @subheading Example usage
3122 Look at the page named @file{2006.January} and then hit @kbd{S-down}
3123 which will show @file{2006.January.Week1}. Then hit @kbd{S-left} and
3124 @kbd{S-right} to look at @file{2006.January.Week2},
3125 @file{2006.January.Week3}, etc.
3127 @subheading Advanced tips and options
3129 You can use any prefix argument with @code{planner-zoom-iup} and
3130 @code{planner-zoom-idown} to have the new view display in a window
3131 other than the current one. This also works with a nonnumeric prefix
3132 argument and @code{planner-zoom-inext} or @code{planner-zoom-iprev}.
3133 For these two functions, a numeric prefix will specify the number of
3136 If you don't like the default patterns for naming the time-period view
3137 pages, you can change them by customizing @code{planner-zoom-regexps}.
3139 Some people believe weeks start with Sunday, and some believe they
3140 start with Monday. To accommodate both of these colliding worldviews,
3141 @code{planner-zoom-first-day-of-week} can be customized. Its default
3142 value is @samp{1}, which is Monday. If you would prefer Sunday, change
3143 it to @samp{0}. The month to which a week belongs is the month in
3144 which the first day of the week falls.
3146 @subheading Command reference
3148 @defun planner-zoom-iup name other-window
3149 Move to the next higher level in the hierarchy. With a prefix
3150 argument, show the desired page in the other window.
3153 @defun planner-zoom-idown name other-window
3154 Move to the next lower level in the hierarchy. If the current date is
3155 within the higher-level time range, zoom to the lower level time range
3156 that also contains today. Otherwise, just go to the first lower-level
3157 time range. With a prefix argument, show the desired page in the other
3161 @defun panner-zoom-inext name num other-window
3162 Move to the next time range at the same level in the hierarchy. With a
3163 numeric prefix argument, move by that number of time ranges. With a
3164 non-numeric prefix argument, show the desired page in the other window.
3167 @defun planner-zoom-iprev name num other-window
3168 Move to the previous time range at the same level in the hierarchy.
3169 With a numeric prefix argument, move by that number of time ranges.
3170 With a non-numeric prefix argument, show the desired page in the other
3174 @node More about Notes, Making Files Pretty, More about Tasks, More about Planner
3175 @section More about Notes
3176 @cindex notes, more about
3178 Planner by default organizes the notes on a planner page so that
3179 the most recent note is first. Each note is numbered, with the oldest
3180 note labeled @samp{.#1}. If you would like to reverse this behavior,
3181 look at @kbd{C-h v planner-reverse-chronological-notes}.
3183 Notes are associated with day pages, but can also be associated with
3184 plan pages when they are created. A linked note looks like this:
3187 .#1 Headline (LinkedNote#1)
3191 You can jump to the linked note with
3192 @command{planner-jump-to-linked-note}.
3194 Deleting a note can be dangerous, as the notes are automatically
3195 numbered. Removing a note could break links in other pages.
3197 @subheading Functions
3199 @defun planner-create-note page
3200 Create a note to be remembered in @var{page} (today if @var{page} is
3201 nil). If @code{planner-reverse-chronological-notes} is non-nil, create
3202 the note at the beginning of the notes section; otherwise, add it to
3203 the end. Position point after the anchor.
3206 @defun planner-create-note-from-task
3207 Create a note based on the current task and update the current task to
3211 @defun planner-renumber-notes
3212 Update note numbering.
3215 @defun planner-jump-to-linked-note note-info
3216 Display the note linked to by the current note or @var{note-info} if
3220 @defun planner-search-notes regexp limit
3221 Return a buffer with all the notes returned by the query for
3222 @var{regexp}. If called with a prefix argument, prompt for
3223 @var{limit} and search days on or after @var{limit}.
3226 The following sections include instructions for displaying,
3227 manipulating, and navigating your notes efficiently.
3230 * Using Allout Mode:: Quickly navigating your notes
3231 * <notes>:: Note headlines
3232 * <past-notes>:: Index of past notes
3233 * Note Indices:: planner-notes-index.el
3236 @node Using Allout Mode, <notes>, More about Notes, More about Notes
3237 @subsection Using Allout Mode
3239 @cindex notes, navigating
3240 @cindex notes, formatting
3241 @cindex notes, displaying
3243 The format of the notes in Planner works well with Allout mode, which
3244 provides helpful commands for navigating and formatting outlines. You
3245 can, for example, hide the bodies of all the notes on a page so you can
3246 see just their headlines. You can also jump easily from headline to
3247 headline, skipping over the bodies in between.
3249 The commands for using Allout mode vary depending on which Emacs version
3250 you are using. In either case, type @kbd{M-x load-library @key{RET}
3251 allout @key{RET}} to start. If you are using CVS Emacs, type @kbd{M-x
3252 allout-mode @key{RET}}. If you are using an earlier version of Emacs,
3253 type @kbd{M-x outline-mode @key{RET}}.
3255 The exact commands then available to you differ depending on your Emacs
3256 version, but you can view the commands and their keybindings by typing
3257 @kbd{C-h m}. In CVS Emacs, they will start with @command{allout-}, while
3258 in previous versions, they will start with @command{outline-}.
3260 @node <notes>, <past-notes>, Using Allout Mode, More about Notes
3263 @samp{<notes>} is replaced by a list of note headlines when the page
3264 is published. For example, the notes tag in the following example will
3265 be replaced by the two headlines when published. (@pxref{Publishing})
3272 .#1 This is a headline
3274 and this is body text
3276 .#2 This is another headline
3278 and this is more body text
3281 @samp{<notes>} is useful if you want to provide a quick summary of
3282 blog entries at the top of your page. Just add it to your
3283 @code{planner-day-page-template}.
3285 @node <past-notes>, Note Indices, <notes>, More about Notes
3286 @subsection <past-notes>
3288 @samp{<past-notes>} is replaced by an index of note headlines.
3289 If @var{start} is specified, it lists notes starting from that date.
3290 If @var{directory} is specified, you can index notes in another
3294 All the notes I've taken in 2004:
3296 <past-notes start="2004.01.01" end="2004.12.31">
3299 @node Note Indices, , <past-notes>, More about Notes
3300 @comment node-name, next, previous, up
3301 @subsection Note Indices
3302 @cindex @file{planner-notes-index.el}, using
3303 @cindex notes, indexing
3305 Make sure that @file{planner-notes-index.el} is in your load path and
3306 add this to your @file{.emacs} (or @file{_emacs}):
3309 (require 'planner-notes-index)
3312 Then you can use tags of the form:
3315 <planner-notes-index page="2004.03.02">
3316 <planner-notes-index from="2004.03.01" to="2004.03.31">
3317 <planner-notes-index limit="10">
3318 <planner-notes-index page="PlanPage">
3319 <planner-notes-index-month-table month="2004.03" limit="5">
3320 <planner-notes-index-month-table month="2004.03">
3323 You can also use the following interactive functions:
3325 @code{planner-notes-index}
3326 @code{planner-notes-index-days}
3327 @code{planner-notes-index-weeks}
3328 @code{planner-notes-index-months}
3329 @code{planner-notes-index-years} (wow!)
3331 These work based on the current date (date of current buffer, or today).
3333 If a single page is specified, this page is scanned for headlines
3340 The results are presented as a bulleted list.
3342 If @var{from} and @var{to} are specified, all date pages between them
3343 (inclusive) are scanned. If @var{from} is omitted, it is assumed to be
3344 the earliest entry. If @var{to} is omitted, it is assumed to be the
3347 If @var{recent} is specified, the list includes only that many recent
3348 headlines. and the results are presented as a bulleted list.
3350 To customize presentation, you can write a function that generates
3351 the appropriate @code{<planner-notes-index>} tags. You can also use
3352 @code{planner-extract-note-headlines} in your own functions.
3354 @subheading Functions
3356 The following interactive functions are defined in
3357 @file{planner-notes-index.el}:
3359 @defun planner-notes-index &optional from to limit
3360 Display a clickable notes index. If called from a Lisp program,
3361 display only dates between @var{from} and @var{to}. With a prefix arg
3362 @var{limit}, display only that number of entries.
3365 @defun planner-notes-index-days days
3366 Display an index of notes posted over the past few @var{days}. The
3367 list ends with the day of the current buffer or @code{planner-today}.
3370 @defun planner-notes-index-weeks weeks
3371 Display an index of notes posted over the past few @var{weeks}. The
3372 list ends with the week of the current buffer or
3373 @code{planner-today}. Weeks start from Sunday.
3376 @defun planner-notes-index-months months
3377 Display an index of notes posted over the past few @var{months}. The
3378 list ends with the month of the current buffer or @code{planner-today}.
3381 @defun planner-notes-index-years years
3382 Display an index of notes posted over the past few @var{years}. The
3383 current year is included.
3386 @file{planner-notes-index.el} does not define any keybindings.
3389 @node Making Files Pretty, Annotations, More about Notes, More about Planner
3390 @section Making Files Pretty
3392 By default, planner does a little bit of fancy reformatting when you
3393 save a file. Tasks are sorted by priority (ABC) and status (_oP>XC) on
3394 day pages. On plan pages, tasks are sorted by priority (ABC), status
3395 (XC), and date. Undated tasks are sorted after dated tasks.
3399 @defopt planner-sort-tasks-key-function
3400 Control task sorting. Some options include
3401 @code{planner-sort-tasks-default-key},
3402 @code{planner-sort-tasks-basic}, @code{planner-sort-tasks-by-date}, and
3403 @code{planner-sort-tasks-by-link}.
3406 @defopt planner-sort-undated-tasks-equivalent
3407 This option controls the behavior of task sorting on plan pages. By
3408 default, the value @samp{9999.99.99} causes dated tasks to be listed
3409 before undated tasks. To sort undated tasks before dated tasks,
3410 set this to a blank string.
3413 @defopt planner-sort-tasks-automatically
3414 Non-nil means sort tasks whenever a planner file is saved. On day
3415 pages, tasks are sorted by status. On plan pages, they are sorted by
3416 status and date. Sorting can take a while.
3419 @defopt planner-renumber-tasks-automatically
3420 Non-nil means renumber tasks from 1 to N whenever a planner file is
3421 saved. This allows you to refer to tasks in previous day pages using
3422 anchors like @samp{2003.08.12#A1}. If you use this function, make sure
3423 @code{planner-use-task-numbers} is non-nil so that new tasks are created
3427 @defopt planner-align-tasks-automatically
3428 Non-nil means align tasks whenever a planner file is saved. This
3429 causes the status to line up in a neat column if you have less than
3433 @defopt planner-renumber-notes-automatically
3434 Non-nil means renumber the notes. If most of your notes are only on
3435 one page, you might like seeing the notes renumbered if you delete a
3436 note in the middle. However, if you use a lot of cross-referencing,
3437 note renumbering will break those links.
3440 @subheading Functions
3442 @defun planner-sort-tasks
3443 Sort tasks according to planner-sort-tasks-key-function. By default,
3444 sort tasks according to priority and position on day pages, and
3445 according to status, priority, date, and position on plan pages.
3448 @defun planner-renumber-tasks
3449 Update task numbering.
3452 @defun planner-align-tasks
3453 Align tasks neatly. You can add this to @code{write-file-functions} to
3454 have the tasks automatically lined up whenever you save. For best
3455 results, ensure @code{planner-align-tasks} is run after
3456 @code{planner-renumber-tasks}.
3459 @defun planner-fix-tasks
3460 Sort, renumber and align tasks.
3463 @node Annotations, Interactive Lisp, Making Files Pretty, More about Planner
3464 @comment node-name, next, previous, up
3465 @section Annotations
3467 The context included when you create a task and the context included
3468 when you create a note are gained the same way. It sounds like black
3469 magic, but it turns out not to be.
3471 All that happens is, Planner has a list of functions,
3472 @code{planner-annotation-functions}. When you create a task from a
3473 buffer, or remember a note from a buffer, Planner goes through
3474 this list from top to bottom. The first one that returns true is the
3477 For example, if you're in Wanderlust, and you hit the key you've bound
3478 to @code{planner-create-task-from-buffer}, it looks at this list and
3479 does something like this. Is it an ERC buffer? No. Is it a BBDB
3480 buffer? No. Are we in w3m? No. Are we in Wanderlust? Yes. So this
3481 function succeeds. It stops searching and runs the annotation function
3482 for Wanderlust, which in this case finds out who the message is from
3483 and what the message ID of the message is. It then takes those and
3484 constructs a link back to that message, with a link title something
3485 like @samp{Email from Joe Blogs}.
3487 So, you've read the email from Joe Blogs. He's asked you to do
3488 something and you've hit your key to add that task to your list of
3489 things to do. So what you end up with is a description of the task,
3490 and a link back to what made you create the task in the first place.
3492 The same happens with remembering notes, except that it ends up in the
3493 @samp{* Notes} section of your page instead.
3495 By default, @file{planner.el} can annotate tasks and notes based on
3496 the current filename.
3500 To change the behavior of annotations, customize the following options:
3502 @defopt planner-annotation-functions
3503 A list of functions tried in order by
3504 @command{planner-create-task-from-buffer} and other functions that
3505 pick up context. The first non-nil value returned is used as the
3506 annotation. To cause an item to @strong{not} be annotated, return the
3507 empty string @samp{""}.
3510 @defopt planner-annotation-strip-directory
3511 File links are usually generated with the full path to the file so
3512 that you can easily tell apart files with the same base name. If
3513 @code{planner-annotation-strip-directory} is non-nil, though, only the
3514 base name of the file will be displayed. For example, a link to
3515 @samp{/foo/bar/baz} will be displayed as @samp{baz} and hyperlinked to
3519 @defopt planner-annotation-use-relative-file
3520 If t, always use relative filenames.
3521 @code{planner-annotation-use-relative-file} can also be a function that
3522 takes the filename and returns non-nil if the link should be relative.
3523 Filenames are resolved relative to the first directory of your Planner
3524 project in @code{muse-project-alist}. That is, the created link will be
3525 of the form @samp{../../somefile} instead of
3526 @samp{/absolute/path/to/file}. This can be helpful if you publish your
3527 planner files to the Net and your directory structure ensures that
3528 relative links resolve the same from your Plan pages and their
3529 respective publishing directory.
3532 @node Interactive Lisp, Publishing, Annotations, More about Planner
3533 @comment node-name, next, previous, up
3534 @section Interactive Lisp with planner-lisp.el
3535 @cindex Lisp functions, using with Planner
3536 @cindex interactive Lisp fuctions, using with Planner
3537 @cindex @file{planner-lisp.el}, using
3539 You can include interactive Lisp functions in your planner pages.
3541 First, you need @file{planner-lisp.el}. Put this in your @file{.emacs}
3545 (require 'planner-lisp)
3548 Then, add a link to the Lisp function to your page, like:
3552 [[lisp:/plan][Plan]]
3556 This will be rendered as @samp{Plan}. Selecting the link will run the
3557 @code{plan} function interactively.
3559 You can also execute other Lisp expressions. For example:
3562 [[lisp:/(planner-goto (planner-expand-name "+7"))][Next week]]
3565 @file{planner-lisp.el} does not provide any interactive functions or
3568 @node Publishing, Experimental Functions, Interactive Lisp, More about Planner
3572 You can publish your planner files to a variety of different formats.
3573 For example, you can publish your planner in HTML and put it on a
3574 normal web server. No special server support is required. This gives
3575 you an easy way to keep other people up to date on your tasks, keep a
3576 web log, or simply organize information.
3578 Published files are stored in the path specified by
3579 @code{muse-project-alist} for your Planner project. Just copy the
3580 contents of this directory to your web server, and you're all set! Of
3581 course, publishing is completely optional.
3583 Here are some more features related to publishing:
3586 * Publishing Planner pages:: planner-publish.el
3587 * Publishing Calendars:: planner-calendar.el
3588 * Authz Access Restriction:: planner-authz.el
3589 * RSS Publication:: Sharing notes with planner-rss.el
3590 * iCal Task Publication:: Sharing tasks with planner-ical.el
3591 * RDF Publication:: planner-rdf.el
3594 @node Publishing Planner pages, Publishing Calendars, Publishing, Publishing
3595 @comment node-name, next, previous, up
3596 @subsection Publishing Planner pages
3598 @cindex @file{planner-publish.el}, using
3600 Publishing works by providing Muse with the settings and environment for
3603 First, make sure that you have set up a proper
3604 @code{muse-project-alist} (@pxref{Creating Your Planner}).
3609 (require 'planner-publish)
3612 to your @file{.emacs} (or @file{_emacs}).
3614 To publish your entire Planner project, hit @kbd{C-c C-p}
3615 (@code{muse-project-publish}). To publish just the current buffer, hit
3616 @kbd{C-c C-t} (@code{muse-publish-this-file}).
3618 To automatically publish files when you save them, add the following
3619 code to your @file{~/.emacs} (or @file{_emacs}):
3622 (eval-after-load "muse-mode"
3623 (add-hook 'after-save-hook
3625 (when (planner-derived-mode-p 'muse-mode)
3626 (muse-project-publish nil)))
3630 @subheading Styles provided
3632 The following publishing styles are available.
3636 @cindex publishing styles, planner-html
3638 Publish Planner pages to HTML.
3640 @cindex publishing styles, planner-xhtml
3642 Publish Planner pages to XHTML.
3644 @cindex publishing styles, planner-xml
3646 Publish Planner pages to XML.
3650 @subheading Options provided
3652 The following options may be customized to enhance your publishing
3657 @item planner-publish-markup-regexps
3658 List of markup rules for publishing Planner pages.
3660 @item planner-publish-markup-functions
3661 Specify which function to use for publishing different kinds of markup.
3663 @item planner-publish-markup-tags
3664 A list of custom HTML-like tags to recognize when publishing.
3666 @item planner-xml-markup-strings
3667 Strings that are inserted to publish XML markup.
3669 @item planner-xml-header
3670 Header used when publishing Planner XML files.
3671 This may be text or a filename.
3673 @item planner-xml-footer
3674 Footer used when publishing Planner XML files.
3675 This may be text or a filename.
3677 @item planner-html-markup-strings
3678 Strings that are inserted to publish HTML markup.
3680 @item planner-html-style-sheet
3681 CSS stylesheet elements used in Planner HTML and XHTML files.
3682 This can also be one or more @samp{<link>} tags.
3684 @item planner-html-header
3685 Header used when publishing Planner HTML files.
3686 This may be text or a filename.
3688 @item planner-html-footer
3689 Footer used when publishing Planner HTML files.
3690 This may be text or a filename.
3692 @item planner-xhtml-header
3693 Header used when publishing Planner XHTML files.
3694 This may be text or a filename.
3696 @item planner-xhtml-footer
3697 Footer used when publishing Planner XHTML files.
3698 This may be text or a filename.
3700 @item planner-html-inner-header
3701 Extra header section that can be embedded within
3702 @code{planner-html-header} and @code{planner-xhtml-header}.
3704 @item planner-html-inner-footer
3705 Extra header section that can be embedded within
3706 @code{planner-html-footer} and @code{planner-xhtml-footer}.
3708 @item planner-publish-prepare-regexps
3709 List of markup rules to apply before publishing a page with Planner.
3711 @item planner-publish-finalize-regexps
3712 List of markup rules to apply after publishing a page with Planner.
3716 @node Publishing Calendars, Authz Access Restriction, Publishing Planner pages, Publishing
3717 @comment node-name, next, previous, up
3718 @subsection Publishing Calendars
3719 @cindex calendar, publishing
3720 @cindex @file{planner-calendar.el}, using
3722 To publish calendars in your day pages, it is necessary to do two steps.
3725 @item Add @code{(require 'planner-calendar)} to your configuration.
3726 @item Add a @samp{<calendar>} tag to either your header, footer, or
3727 @var{planner-day-page-template}, depending on where you want it to
3731 To display a calendar based on a different day (given here as DAYPAGE),
3732 use @code{<calendar page="DAYPAGE">}.
3734 To get arrows to previous and next months to show up, use
3735 @code{<calendar arrows="t">}. The text in
3736 @var{planner-calendar-prev-month-button} and
3737 @var{planner-calendar-next-month-button} will be used for the arrows to
3738 the previous and next months, respectively.
3740 By default, Muse will not display the arrows properly, due to
3741 limitations in the special-escaping algorithm. To work around this,
3742 remove the @samp{&} rule from @var{muse-xml-markup-specials}, or from
3743 @var{muse-html-markup-specials} if you are using the 3.02.6 version of
3746 It is also possible to create a symlink from the current day page to the
3747 page name specified by @var{planner-calendar-today-page-name}. To
3748 accomplish this, add the following to your configuration.
3751 (eval-after-load "muse-publish"
3752 '(add-hook 'muse-after-publish-hook
3753 'planner-calendar-create-today-link))
3758 @defopt planner-calendar-prev-month-button
3759 HTML text used for previous month buttons.
3762 @defopt planner-calendar-next-month-button
3763 HTML text used for next month buttons.
3766 @defopt planner-calendar-day-header-chars
3767 Number of characters to use for day column header names.
3770 @defopt planner-calendar-today-page-name
3771 Default name for published today page link.
3774 @subheading Functions
3776 @defun planner-calendar-create-today-link
3777 Add this function to @code{muse-after-publish-hook} to
3778 create a ``today'' soft-link to the newest published planner day page,
3779 on operating systems that support POSIX @command{ln}.
3782 @node Authz Access Restriction, RSS Publication, Publishing Calendars, Publishing
3783 @comment node-name, next, previous, up
3784 @subsection Authz Access Restriction
3785 @cindex @file{planner-authz.el}, using
3786 @cindex Mason, restricting portions with
3787 @cindex access, restricting
3789 @file{planner-authz.el} was written by Andrew J. Korty in order to
3790 allow the easy restriction of portions of published pages. It uses
3791 the HTML::Mason module available on CPAN
3792 (@url{http://www.cpan.org}). Setting up HTML::Mason is
3793 outside the scope of this document. Make sure that it works before
3794 trying out @file{planner-authz.el}.
3796 @file{planner-authz.el} modifies the behavior of
3797 @command{muse-project-publish} so that published pages follow access
3800 This library lets you publish your planner pages while controlling
3801 access to certain portions of them to users you specify. When you
3802 load this library, you gain access to two additional markup directives
3803 to use in your planner pages. The @samp{<authz>} tag lets you
3804 restrict access to arbitrary content as follows:
3807 Here is a sentence everyone should see. This sentence also
3808 contains no sensitive data whatsoever. <authz users="ajk">This
3809 sentence, however, talks about my predilection for that French
3810 vanilla instant coffee that comes in the little tin, and I'm
3811 embarrassed for anyone else to know about that.</authz> And
3812 here's some more perfectly innocuous content.
3815 You can use @samp{<authz>} tags to mark up entire paragraphs, tasks,
3816 notes, and anything else. The tags are replaced with Mason code in
3817 the published pages.
3819 The @samp{#authz} directive restricts access to an entire page. A Mason
3820 call is added to this page to generate a 403 error when someone not
3821 listed tries to access it. Any notes or tasks on a
3822 @samp{#authz}-protected page are also wrapped in Mason code on linked
3823 pages. To add a @samp{#authz} directive to a Muse page, place
3824 @samp{#authz} followed by a space-delimited list of users on one
3831 @subheading Getting started
3833 Add the following to your .emacs file to cause @kbd{M-x
3834 muse-project-publish} to automatically use planner-authz features.
3837 (require 'planner-authz)
3840 @subheading Diary markup
3842 If your pages have a section with diary entries maintained by
3843 planner-appt.el (or by any other means), you can control access to these
3844 entries. First, customize @code{planner-section-tagnames} to map your
3845 diary section ("* Schedule", in this example) to a tag called
3846 "diary-section". An example follows.
3849 (add-to-list 'planner-section-tagnames '("Schedule" . "diary-section"))
3852 If the name of your diary section is "* Diary", you will not need to
3853 customize @code{planner-section-tagnames} by default.
3855 Then make sure the diary entries you want restricted contain a
3856 corresponding plan page name in parentheses, as in the following
3860 10:00 10:30 Meeting with boss (WorkStuff)
3865 @defopt planner-authz-project-default
3866 Default access list for project pages (not day pages). If a given
3867 project page doesn't contain a @samp{#authz} tag, it will receive the
3868 access list defined here. If this variable is nil, all users will be
3869 allowed to view the page. No corresponding variable is provided for
3870 day pages because it doesn't seem like you'd ever want to control
3871 access based on what day it was. (But I will accept patches. :) Notes
3872 and tasks referencing pages without @samp{#authz} tags will also be
3873 restricted to the users listed here.
3876 @defopt planner-authz-day-note-default
3877 Default access list for notes on day pages not associated with
3878 any project. There is way to set a default for notes on project
3879 pages for the reason above; they would only be associated with
3883 @defopt planner-authz-day-task-default
3884 Same as @kbd{planner-authz-day-note-default}, but for tasks.
3887 @subheading Functions
3889 @defun planner-authz-publish-index
3890 Publish an index for the planner marked up with Mason code.
3891 Only those links to pages which the remote user is authorized to
3892 access will be shown.
3895 @node RSS Publication, iCal Task Publication, Authz Access Restriction, Publishing
3896 @comment node-name, next, previous, up
3897 @subsection RSS Publication
3898 @cindex @file{planner-rss.el}, using
3902 @file{planner-rss.el} allows you to publish your notes in the RSS 2.0
3903 XML format for blog syndication. You will also want to customize the
3904 following variables:
3906 To manually add the current note to all the matching RSS feeds, invoke
3907 @command{planner-rss-add-note}. You can specify a filename with the
3908 universal prefix, like this: @kbd{C-u M-x planner-rss-add-note}.
3910 If you use the @file{remember-planner.el} module to create notes, you
3911 can automatically publish new notes to RSS feeds by adding the
3912 following code to your @file{.emacs} (or @file{_emacs}).
3915 (add-to-list 'remember-planner-append-hook 'planner-rss-add-note t)
3920 @defopt planner-rss-base-url
3921 Base absolute URL for published blog entries. Should include trailing
3925 @defopt planner-rss-category-feeds
3926 Rules for automatic categorization of posts and publishing to RSS
3927 files. A blog entry is matched against each condition. If it matches
3928 the regular expression or the function returns a non-nil value, the
3929 blog entry is copied into the specified file.
3932 @defopt planner-rss-feed-limits
3933 A list of regular expressions that match feed filenames and the size
3934 and item limits for feeds that match. For example, you can use
3935 @samp{(("." nil 10))} to ensure that all feeds are limited to the 10
3939 @subheading Functions
3941 @file{planner-rss.el} defines the following interactive functions:
3943 @defun planner-rss-add-note @var{feed}
3944 Export the current note using @code{planner-add-item}. If @var{feed}
3945 is specified, add the entry to the specified file. Else, add the entry
3946 to all matching RSS feeds specified by
3947 @code{planner-rss-category-feeds}.
3950 @node iCal Task Publication, RDF Publication, RSS Publication, Publishing
3951 @comment node-name, next, previous, up
3952 @cindex @file{planner-ical.el}, using
3953 @subsection iCal Publication
3955 iCal is an Internet Engineering Task Force (IETF) standard for
3956 calendaring and scheduling. @uref{http://www.ietf.org/rfc/rfc2445.txt}
3958 You can export your tasks to the iCal format using
3959 @file{planner-ical}. Add @code{(require 'planner-ical)} to your
3960 @file{~/.emacs}. Then you can use @kbd{M-x planner-ical-export-page}
3961 to display the iCal equivalent of tasks on a page, which you can then
3964 To export today's tasks to a file in your publishing directory, add
3965 the following to your @file{~/.emacs}.
3968 (planner-ical-export-file
3972 (muse-style-element :path (car (cddr (muse-project planner-project))))))
3975 @subheading Functions
3977 @defun planner-ical-export-page page &optional file
3978 Export PAGE's tasks in the iCal format.
3979 If FILE is non-nil, results are saved to that file.
3980 If FILE is nil, results are displayed in a `planner-ical-export-buffer'.
3983 @defun planner-ical-export-this-page
3984 Display the tasks on the current page in iCal format.
3987 @node RDF Publication, , iCal Task Publication, Publishing
3988 @comment node-name, next, previous, up
3989 @subsection RDF Publication
3990 @cindex @file{planner-rdf.el}, using
3991 @cindex RDF, publishing to
3993 Put planner-rdf.el in a directory that is in your Emacs load-path and
3994 the following into your ~/.emacs file:
3997 (require 'planner-rdf)
3998 (eval-after-load "muse-publish"
4000 (add-hook 'muse-after-publish-hook
4001 'planner-rdf-publish-file)
4002 (add-hook 'muse-after-publish-hook
4003 'planner-rdf-publish-index)))
4007 * Publishing with planner-rdf::
4008 * planner-rdf Tags::
4009 * planner-rdf Usage Examples::
4012 @node Publishing with planner-rdf, planner-rdf Tags, RDF Publication, RDF Publication
4013 @subsubsection Publishing with planner-rdf
4015 Planner-rdf is now included in the normal Planner publishing process.
4016 Pressing @key{C-p} will create a .owl and a .rdf file for every planner
4017 file. Additionally it creates an index, @file{index.rdf}.
4019 By default all generated files will be stored in the normal Planner
4020 publishing directory, where the HTML files end up. If you would ike to
4021 change that, set the variable @code{planner-rdf-directory} to the desired
4024 The generated files:
4028 @file{index.rdf} - a collection with pointers to the
4029 @file{<plan-page>.rdf} files.
4031 @file{<plan-page>.rdf} - contains Dublin Core metadata about the files
4032 related to the current Planner page. Currently it contains metadata
4033 about the source file, the Emacs plan page, the generated HTML page, and
4034 the generated OWL file.
4036 @file{<plan-page>.owl} - contains task and note data from the Planner
4037 file. Task information is stored completely. For notes, the note
4041 @node planner-rdf Tags, planner-rdf Usage Examples, Publishing with planner-rdf, RDF Publication
4042 @subsubsection planner-rdf Tags
4044 Besides the factual information, e.g. the task status or description,
4045 planner-rdf extracts links (in the format @samp{[[...][...]]} or
4046 @samp{[[...]]}) and tags (@samp{@{@{...:...}@}@}) from tasks and notes
4047 (including the notes text). Links and tags provide context for the plan
4048 elements and so are stored and linked with the containing elements.
4050 Links point to locations that can be used to enrich the information in
4051 the Planner pages (e.g, by retrieving data from them and adding it),
4052 tags -- like the one for the task ids @samp{@{@{Tasks:198@}@}} -- can be
4053 used to express abstract qualities. Some examples:
4057 an @samp{@{@{audience:myteam@}@}} tag, can be used to restrict
4058 publishing of items to a certain user group;
4059 @item a @samp{@{@{lang:de@}@}} tag, signifying the language of the text;
4061 a @samp{@{@{location:Hamburg@}@}} tag, can be used to make geographic
4062 reference to an entity that is not stored in your address book, bbdb.
4065 What tags to use is up to the user. Planner-rdf makes no assumptions
4066 about them, it just extracts and stores them. Only the applications
4067 using the data know what to do with them.
4069 @node planner-rdf Usage Examples, , planner-rdf Tags, RDF Publication
4070 @subsubsection Usage Examples
4072 Report generation with OpenOffice
4074 The Perl file @file{this-week.pl}
4075 (@url{http://www.rainervolz.de/planner-rdf/this-week.pl}) creates a
4076 simple report for the current week. The script extracts task and note
4077 information from the generated OWL files and inserts it into a simple
4078 OpenOffice Writer document. Nothing fancy, just a proof of concept, to
4079 show how planner-rdf can be used to integrate Planner Mode with other
4082 Besides Perl and OpenOffice you'll need the Redland RDF Application
4083 Framework (@url{http://www.redland.opensource.ac.uk/}). It is used to
4084 process the RDF data. Redland is small, but powerful, and available
4085 for many platforms and languages.
4087 As an example the application loads the RDF data each time it is run.
4088 In the real world you probably would use Redland to store the Planner
4089 data in a database, to save the loading step each time you access the
4092 Importing Planner data into Protege
4094 Protege is a popular ontology editor and knowledge management
4095 application. A simple way to import data into it, is to provide a OWL
4096 file that contains the data as well as the schema. To do this:
4100 Use @file{planner2protege.pl}
4101 (@url{http://www.rainervolz.de/planner-rdf/planner2protege.pl}) to
4102 combine all OWL files into a single one.
4104 Use CWM (@url{http://www.w3.org/2000/10/swap/doc/cwm.html}) to combine
4105 schema and data, with @code{python cmw --rdf planner-rdf.owl
4106 planner-data.owl --think --rdf >planner2.owl}
4109 Not the most straightforward process, but it works. The resulting file,
4110 here planner2.owl, can then be loaded into Protege.
4112 @node Experimental Functions, , Publishing, More about Planner
4113 @comment node-name, next, previous, up
4114 @section Experimental Functions
4115 @cindex @file{planner-experimental.el}, using
4116 @cindex experimental functions, Planner
4118 These functions are experimental. This means that they may not do
4119 exactly what you expect them to do, so keep backups, be careful, and
4122 To use these functions, make sure that @file{planner-experimental.el} is
4123 in your load path, and add this to your @file{.emacs} (or
4127 (require 'planner-experimental)
4130 @subheading Functions
4132 @file{planner-experimental.el} defines the following interactive
4135 @defun planner-search-notes-next-match
4136 Jump to the next matching entry. Call after
4137 @code{planner-search-notes}.
4140 @defun planner-search-notes-previous-match
4141 Jump to the previous matching entry. Call after
4142 @code{planner-search-notes}.
4145 @defun planner-remove-duplicates
4146 Remove duplicate tasks.
4149 @file{planner-experimental.el} does not define any keybindings.
4151 @node Managing Your Information, Advanced Configuration, More about Planner, Top
4152 @comment node-name, next, previous, up
4153 @chapter Managing Your Information
4155 Planner can be integrated with other Emacs and even some non-Emacs
4156 programs by loading additional modules. You can pick and choose from
4157 these modules, choosing those that work with programs you use and that
4158 produce information you want to have included in your Planner pages.
4161 * E-mail:: Linking notes and tasks to messages
4162 * Scheduling and Time:: Tracking appointments and where your time goes
4163 * Finances:: Display your account balances and more
4164 * Contacts and Conversations:: BBDB and ERC
4165 * Tracking Research and Resources:: The Web, bibliographies, and bookmarks
4166 * Tracking Development::
4169 @node E-mail, Scheduling and Time, Managing Your Information, Managing Your Information
4170 @comment node-name, next, previous, up
4173 Planner can work together with several different Emacs e-mail
4174 clients. If you load the appropriate module for the e-mail client you
4175 use, then your notes and tasks can be annotated with information
4176 pointing to the specific e-mail message you were reading when you
4177 created that note or task. When you are looking at the note or task, you
4178 will be able to jump straight to that message.
4181 * Unix mail:: Unix mailboxes: planner-unix-mail.el
4182 * Gnus:: Gnus mail and news reader: planner-gnus.el
4183 * VM:: VM mail reader: planner-vm.el
4184 * Wanderlust:: Wanderlust mail reader: planner-wl.el
4185 * MH-E:: MH-E mail reader: planner-mhe.el
4186 * Rmail:: Rmail: planner-rmail.el
4190 @node Unix mail, Gnus, E-mail, E-mail
4191 @comment node-name, next, previous, up
4192 @subsection Unix mail
4193 @cindex @file{planner-unix-mail.el}, using
4194 @cindex mbox, using Planner with
4195 @cindex Unix mail, using Planner with
4196 @cindex mail client, using Planner with
4198 This module supports links from any kind of Unix mailbox (mbox). To
4199 use this module, make sure that @file{planner-unix-mail.el} is in your
4200 load path and add this to your @file{.emacs} (or @file{_emacs}):
4203 (require 'planner-unix-mail)
4206 Unix mail URLs are of the form:
4209 ;; mail://PATH/TO/INBOX/message-id
4212 Annotations will be of the form:
4215 [[mail://PATH/TO/INBOX/E1AyTpt-0000JR-LU%40sacha.ateneo.edu][E-mail from Sacha Chua]]
4218 @file{planner-unix-mail.el} does not define any interactive functions or
4219 create any new keybindings.
4221 @node Gnus, VM, Unix mail, E-mail
4222 @comment node-name, next, previous, up
4224 @cindex Gnus, using Planner with
4225 @cindex mail client, using Planner with, Gnus
4226 @cindex @file{planner-gnus.el}, using
4228 To use this module, make sure that it is in your load path and put
4229 this in your @file{.emacs} (or @file{_emacs}):
4232 (require 'planner-gnus)
4233 (planner-gnus-insinuate)
4236 With this module loaded, when you create tasks from Gnus summary or
4237 message buffers, the tasks will be annotated with information from the
4238 message you were looking at when you created each task. A link will also
4239 be created on your planner page that you can select in order to return
4242 So, the created task will look something like this:
4245 #A34 _ Send writing to publishme.com from
4246 [[gnus://alt.books.beatgeneration/<Ifo5c.24632$F9.9567@@nwrddc01.gnilink.net>][E-Mail
4247 from editor@@verizon.net]] @{@{Tasks:71@}@} ([[Writing]])
4250 This module also binds @kbd{C-c C-t} in the Gnus summary and article
4251 views to the command to create a new task.
4253 @file{planner-gnus.el} does not define any interactive functions.
4255 For more information about Gnus, see @inforef{Top, The Gnus Newsreader,
4258 @node VM, Wanderlust, Gnus, E-mail
4259 @comment node-name, next, previous, up
4261 @cindex VM, using Planner with
4262 @cindex mail client, using Planner with, VM
4263 @cindex @file{planner-vm.el}, using
4265 To use this module, make sure that @file{planner-vm.el} is in your load
4266 path and add this to your @file{.emacs} (or @file{_emacs}):
4269 (require 'planner-vm)
4272 VM URLs are of the form:
4275 vm://path/to/inbox/message-id
4278 Annotations will be of the form:
4281 [[vm://home/test/INBOX/<E1AyTpt-0000JR-LU@@sacha.ateneo.edu>][E-mail from Sacha Chua]]
4284 @file{planner-vm.el} does not define any interactive functions or
4288 @node Wanderlust, MH-E, VM, E-mail
4289 @comment node-name, next, previous, up
4290 @subsection Wanderlust
4291 @cindex Wanderlust, using Planner with
4292 @cindex mail client, using Planner with, Wanderlust
4293 @cindex @file{planner-wl.el}, using
4295 To use this module, make sure that @file{planner-wl.el} is in your
4296 load path and add this to your @file{.emacs} (or @file{_emacs}):
4299 (require 'planner-wl)
4302 Then, when you call @kbd{M-x planner-create-task-from-buffer} from
4303 Wanderlust summary or message buffers, the task will be created with
4304 the correct annotation.
4306 @file{planner-wl} does not define any interactive functions.
4310 To add keybindings to Wanderlust, call:
4313 (planner-wl-insinuate)
4316 This binds @kbd{F} to @command{planner-create-task-from-buffer}.
4318 @node MH-E, Rmail, Wanderlust, E-mail
4319 @comment node-name, next, previous, up
4321 @cindex MH-E, using Planner with
4322 @cindex mail client, using Planner with, MH-E
4323 @cindex @file{planner-mhe.el}, using
4325 To use this module, make sure that @file{planner-mhe.el} is in your
4326 load path and add this to your @file{.emacs} (or @file{_emacs}):
4329 (require 'planner-mhe)
4332 Then, when you call @kbd{M-x planner-create-task-from-buffer} from
4333 MH-E summary or message buffers, the task will be created with
4334 the correct annotation.
4336 @file{planner-mhe} does not define any interactive functions.
4338 @node Rmail, , MH-E, E-mail
4339 @comment node-name, next, previous, up
4341 @cindex Rmail, using Planner with
4342 @cindex mail client, using Planner with, Rmail
4343 @cindex @file{planner-rmail.el}, using
4345 To use this module, make sure that @file{planner-rmail.el} is in your
4346 load path and add this to your @file{.emacs} (or @file{_emacs}):
4349 (require 'planner-rmail)
4352 Rmail URLs are of the form:
4358 Annotations will be of the form:
4361 [[rmail://<E1AyTpt-0000JR-LU@@sacha.ateneo.edu>][E-mail from Sacha Chua]]
4364 @file{planner-rmail.el} does not define any interactive functions or
4365 create any new keybindings.
4367 For more information about Rmail, see @inforef{Rmail, Reading Mail With
4370 @node Scheduling and Time, Finances, E-mail, Managing Your Information
4371 @comment node-name, next, previous, up
4372 @section Scheduling and Time
4375 * Diary:: Using the Emacs diary: planner-diary.el
4376 * Appointments:: Appointments in plan pages: planner-appt.el
4377 * Timeclock:: Time tracking: planner-timeclock.el
4378 * schedule.el:: Project completion: planner-schedule.el
4382 @node Diary, Appointments, Scheduling and Time, Scheduling and Time
4383 @comment node-name, next, previous, up
4385 @cindex diary, using Planner with
4386 @cindex @file{planner-diary.el}, using
4388 If you use Emacs's diary feature, Planner-Diary could be helpful for
4389 you. It puts all diary entries for the current day in the @samp{*
4390 Diary} section of your day plan page. This section is updated every
4391 time you display the file in Emacs. By default the diary section of
4392 past pages is not updated; it's pretty unlikely that you want to add
4393 new diary entries for the past. (@pxref{Diary, , , Emacs, GNU Emacs
4396 If you want to use @file{planner-diary.el}, make sure the file is in
4397 your load path and add this to your @file{.emacs} (or @file{_emacs}):
4400 (require 'planner-diary)
4403 @file{planner-diary.el} needs @command{fancy-diary-display}. To use
4404 @command{fancy-diary-display}, add this to your @file{.emacs} (or
4408 (add-hook 'diary-display-hook 'fancy-diary-display)
4411 You can use Planner-Diary in two different ways:
4416 If you want the saved files to contain your entries and not just a line
4417 of Lisp, add the following lines to your @file{.emacs} (or @file{_emacs}):
4420 (setq planner-diary-use-diary t)
4421 (planner-diary-insinuate)
4424 You should also customize or set @code{planner-day-page-template} to
4425 include a @samp{* Diary}:
4428 (setq planner-day-page-template
4429 "* Tasks\n\n\n* Schedule\n\n\n* Diary\n\n\n* Notes")
4433 (GNU EMACS ONLY) You can put the following line of Lisp code in your
4434 day plan pages to display your diary entries:
4437 <lisp>(planner-diary-entries-here)</lisp>
4440 You can do this automatically for all day plan pages:
4443 (setq planner-day-page-template
4444 "* Tasks\n\n\n* Diary\n\n<lisp>(planner-diary-entries-here)</lisp>
4448 When you open a day plan page outside Emacs, you will see the line of
4449 Lisp code and not your diary entries.
4453 If you want to see your diary entries for more than just one day, set
4454 @code{planner-diary-number-of-days} accordingly. This works for either
4455 of the two approaches.
4457 @kbd{C-c C-e} updates the diary sections. @kbd{C-u C-c C-e} forces an
4458 update---it inserts the diary section for the day, even if the day is in
4459 the past or if there is no @samp{Diary} section in the buffer.
4461 These diary sections are only intended for display. Editing them will
4462 not affect your diary file. If you want to add entries to your diary,
4463 you should use the usual Emacs diary and calendar methods for doing
4464 that, or call @code{planner-diary-add-entry}.
4466 If you want to use the Cal-Desk package, simply follow the instructions
4467 in @file{cal-desk.el}. If you get the Cal-Desk layout from the Calendar
4468 buffer, you get it in the day plan buffer, too.
4470 If you use Planner-Diary, you might consider using the Calendar support
4471 of Planner. (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) To get
4472 Calendar integration, add this to your @file{.emacs} (or @file{_emacs}):
4475 (planner-insinuate-calendar)
4478 If @code{planner-diary-create-section-flag} is non-nil, sections are
4479 always inserted if necessary.
4481 @cindex planner2diary.py, using
4482 If you want to import Planner entries into your Diary file, the
4483 @file{planner2diary.py} script will accomplish this for you. To use it,
4484 execute @code{planner2diary.py} on the command line, specifying your
4485 planner directory as the first and only argument.
4489 @defopt planner-diary-create-section-flag
4490 Non-nil means create the requested diary sections if they do not
4491 exist. By default, planner-diary tries to create the section. If you
4492 want more control over your pages, you can set this to nil. Trying to
4493 write a diary section to a page that does not have it yet will then
4497 By default, planner-diary lists only the appointments you have on that
4498 day. If you want the date headers included even when showing the diary
4499 entries for a single day, set planner-diary-include-all-output to
4502 @defopt planner-diary-include-all-output-flag
4503 Non-nil means don't omit any data when copying diary entries into day
4507 @subheading Functions
4509 @file{planner-diary.el} defines the following interactive functions:
4511 @defun planner-diary-add-entry date time text
4512 Prompt for a diary entry to add to @code{diary-file} on @var{date}.
4513 Uses @code{planner-annotation-functions} to make hyperlinks.
4514 @var{time} and @var{text} are used in the description."
4517 @defun planner-diary-insert-diary force
4518 Insert the fancy diary for the day into the day plan file. If
4519 @var{force} is non-nil, insert a diary section even if there is no
4520 @var{planner-diary-string} in the buffer.
4523 @defun planner-diary-insert-diary-maybe force
4524 Maybe insert the fancy diary for the day into the day plan file. If the
4525 current day is in the past and @var{force} is nil, don't do anything. If
4526 @var{force} is non-nil, insert a diary section even if there is no
4527 @code{planner-diary-string} in the buffer.
4530 @defun planner-diary-insert-appts force
4531 Insert the diary appointments for the day into the day plan file. If
4532 @var{force} is non-nil, insert a diary appointments section even if
4533 there is no @code{planner-diary-appts-string} in the buffer.
4536 @defun planner-diary-insert-appts-maybe force
4537 Maybe insert the diary appointments for the day into the day plan file.
4538 If the current day is in the past and @var{force} is nil, don't do
4539 anything. If @var{force} is non-nil, insert a diary appointments
4540 section even if there is no @code{planner-diary-appts-string} in the
4544 @defun planner-diary-insert-cal-desk force
4545 Insert the cal-desk diary for the day into the day plan file. If
4546 @var{force} is non-nil, insert a cal-desk diary section even if there is
4547 no @code{planner-diary-cal-desk-string} in the buffer.
4550 @defun planner-diary-insert-cal-desk-maybe force
4551 Maybe insert the cal-desk diary for the day into the day plan file. If
4552 the current day is in the past and @var{force} is nil, don't do
4553 anything. If @var{force} is non-nil, insert a cal-desk appointments
4554 section even if there is no @code{planner-diary-cal-desk-string} in the
4558 @defun planner-diary-insert-public force
4559 Insert the public diary for the day into the day plan file. If
4560 @var{force} is non-nil, insert a public diary section even if there is
4561 no @code{planner-diary-public-string} in the buffer.
4564 @defun planner-diary-insert-public-maybe force
4565 Maybe insert the public diary for the day into the day plan file. If
4566 the current day is in the past and @var{force} is nil, don't do
4567 anything. If @var{force} is non-nil, insert a public appointments
4568 section even if there is no @code{planner-diary-public-string} in the
4572 @defun planner-diary-insert-private force
4573 Insert the private diary for the day into the day plan file. If
4574 @var{force} is non-nil, insert a private diary section even if there is
4575 no @code{planner-diary-private-string} in the buffer.
4578 @defun planner-diary-insert-private-maybe force
4579 Maybe insert the private diary for the day into the day plan file. If
4580 the current day is in the past and @var{force} is nil, don't do
4581 anything. If @var{force} is non-nil, insert a private appointments
4582 section even if there is no @code{planner-diary-private-string} in the
4586 @defun planner-diary-insert-all-diaries force
4587 Update all diary sections in a day plan file. If @var{force} is
4588 non-nil, insert a diary section even if there is no section header. It
4589 only inserts diaries if the corresponding @code{planner-diary-use-}*
4590 variable is @samp{t}.
4593 @defun planner-diary-insert-all-diaries-maybe force
4594 Update all diary sections in a day plan file. If the current day is in
4595 the past and @var{force} is nil, don't do anything. If @var{force} is
4596 non-nil, insert a diary section even if there is no section header. It
4597 only inserts diaries if the corresponding @code{planner-diary-use-}*
4598 variable is @samp{t}.
4601 @defun planner-diary-show-day-plan-or-diary
4602 Show the day plan or diary entries for the date under point in calendar.
4603 Add this to @code{calendar-move-hook} if you want to use it. In that
4604 case, you should also @command{remove-hook} @samp{planner-calendar-show}
4605 from @code{calendar-move-hook}.
4610 @file{planner-diary.el} adds the following keybinding to Planner, if
4611 @command{planner-diary-insinuate} is in your @file{.emacs} (or
4617 @kbd{C-c C-e} updates the diary sections by calling
4618 @code{planner-diary-insert-all-diaries-maybe}.
4623 * Planner-Diary Advanced Features::
4626 @node Planner-Diary Advanced Features, , Diary, Diary
4627 @comment node-name, next, previous, up
4628 @subsubsection Planner-Diary Advanced Features
4629 @cindex diary, using Planner with
4630 @cindex @file{planner-diary.el}, advanced features
4632 The features described here are part of the development version. They
4633 are subject to change without notice. They may be buggy. The
4634 documentation may be inaccurate. Use at your own risk.
4636 There is a lot of code redundancy in the development version. This is
4637 intentional and makes it easier to change the code for one type of diary
4638 section without breaking others.
4640 @subheading Diary views
4642 @cindex @file{planner-diary.el}, views
4643 Currently Planner-Diary supports six different views of your diary
4648 Ordinary fancy diary display (what you get by pressing @kbd{d} in the
4649 calendar buffer with @code{fancy-diary-display} switched on)
4652 Schedule/Appointments (all entries from 1 that have a time assigned to
4656 Diary without appts (1 without 2)
4659 cal-desk display (appts on top, non appts entries at bottom)
4662 A private diary (same as 1, but uses a different diary-file)
4665 A public diary (same as 1, but uses a different diary-file)
4668 Put the following line of Lisp code in your day plan pages to display
4672 <lisp>(planner-diary-entries-here)</lisp>
4675 The function @code{planner-diary-entries-here} takes two optional
4676 arguments---the diary file you want to use and the number of days you
4679 @subheading Exporting Planner-specific Diary files
4681 @cindex @file{planner-diary.el}, exporting entries
4682 If you would like to export diary entries from your Planner pages to
4683 separate Diary files, add @code{(require 'planner-export-diary)} to your
4684 config. The following steps describe the usage of the functions and
4685 options contained in this file.
4690 Customize @code{planner-export-diary-file}. The default value is
4691 ``~/diary.planner''.
4694 Add the following line to your main Diary file (default: ``~/diary'').
4697 #include ~/diary.planner
4701 Then, call @command{M-x planner-export-diary-future} whenever you want
4702 future diary entries published. You can automatically publish entries by
4703 adding either of the following to your .emacs.
4707 @item (planner-export-diary-future)
4708 Publish future entries on startup.
4710 @item (add-hook 'planner-mode-hook 'planner-export-diary-setup)
4711 Publish future entries whenever you save a Planner file.
4717 @node Appointments, Timeclock, Diary, Scheduling and Time
4718 @comment node-name, next, previous, up
4719 @subsection Appointments
4720 @cindex appointments
4721 @cindex @file{planner-appt.el}, using
4723 If you would like to use planner for your appointment alerts
4724 instead of using the diary system, you might like to try
4725 @file{planner-appt}.
4727 According to your preferences, you may choose from two different
4728 approaches. Appointments in task descriptions on today's plan
4732 #A _ @@12:45 Do something (TaskPool)
4736 and appointments in today's schedule section are like this:
4741 9:00 | 12:00 | Read Simmel's Philosophy of Money
4742 @@12:45 | | Do Something Else
4743 @@13:00 | 14:00 | lunch
4747 You can even use both at the same time if you like.
4749 @c Jim Ottaway <j.ottaway@lse.ac.uk>: Changed these kinds of heading
4750 @c back to @unnumberedsec, but left the originals commented out in
4751 @c case there was a good reason for the @strong formatting.
4755 @unnumberedsubsubsec Usage
4757 In the file where you configure Planner, add one of the following.
4761 For task-based appointments: @code{(planner-appt-use-tasks)}
4763 For schedule-based appointments: @code{(planner-appt-use-schedule)}
4765 For both task- and schedule-based appointments:
4766 @code{(planner-appt-use-tasks-and-schedule)}
4770 And finally if you want everything to be updated automatically add:
4773 (planner-appt-insinuate)
4776 If you don't want to do the insinuation then you can call:
4779 M-x planner-appt-update
4783 after editing appointments on the page (note that this is not
4784 necessary if you use tasks for the appointments and you don't edit
4785 the task descriptions outside of @code{planner-edit-task-description}).
4787 Try both methods; if you find that you prefer one over the
4788 other, use one of the specific @code{planner-appt-use-} functions, as
4789 there are some performance gains when using one method exclusively.
4792 * Task-based Appointments::
4793 * Schedule-based Appointments::
4794 * Viewing Appointments::
4795 * Appointment Updating on Save::
4796 * Appointment and Calendar Integration::
4797 * Appointment Hooks::
4801 @node Task-based Appointments, Schedule-based Appointments, Appointments, Appointments
4802 @comment node-name, next, previous, up
4803 @subsubsection Task-based Appointments
4804 @cindex appointments, task-based
4805 @cindex task-based appointments
4807 A task has an appointment if it looks like this:
4810 #A _ @@12:45 Do something (TaskPool)
4814 i.e., if it has @@ followed by a time at the beginning. This means
4815 the task is a regular appointment, and will not be carried forward
4816 at the start of a new day.
4818 Alternatively, it may have a !, like this:
4821 #A _ !12:45 Do something else (TaskPool)
4825 This makes it a "nagging" appointment, which @emph{will} be carried
4826 forward. It will, however, lose the appointment time in the
4829 This may seem like a strange feature, but here is Henrik's
4833 Sometimes I have a task that I want to do at a certain time, so I
4834 make it an appointment. If I don't get around to doing it anyway,
4835 I want it to be carried forward. Basically, I sometimes use
4836 appointments on tasks to annoy me until I get them done. :)
4839 You can edit, move and delete tasks with the usual functions, and
4840 appointments will be updated automatically.
4842 You can update all task appointments on your page with
4845 M-x planner-appt-update
4849 @c @strong{Cyclic Entries}
4851 @unnumberedsubsubsec Cyclic Entries
4852 @cindex appointments, cyclic task entries
4854 If you have @file{planner-cyclic} (@pxref{Cyclic Tasks}) loaded, entries
4855 in your cyclical tasks file such as
4858 Friday #A _ @@12:45 staff meeting
4862 will appear every Friday and there will be an appointment alert set
4866 @c @strong{Appointments Section}
4867 @unnumberedsubsubsec Appointments Section
4868 @cindex appointments, appointments section
4870 You can have all task-based appointments copied to a separate section,
4871 providing an overview of your appointments.
4876 (setq planner-appt-task-use-appointments-section-flag t)
4879 @noindent to your configuration, or use @kbd{M-x customize-variable}.
4881 The variable @code{planner-appt-task-appointments-section} is the name
4882 of the section where the appointments will be copied. By default, it is
4883 set to @code{"Schedule"}, which means that task appointments will be
4884 intermingled with schedule entries.
4886 It is also a good idea to add the section you wish to use to
4887 @code{planner-day-page-template} in order to control where that section
4888 will appear on the page (otherwise it will appear at the top).
4890 The format of the appointments follows that of a schedule; if you
4891 don't like the way it looks, you can write something different and set
4892 @code{planner-appt-format-appt-section-line-function} appropriately.
4893 See the documentation for
4894 @code{planner-appt-format-appt-section-line-function} for details. It
4895 should be fairly easy to see what needs to be done if you look at the
4896 source for the default function (which is
4897 @code{planner-appt-format-appt-section-line}).
4899 If the section specified in
4900 @code{planner-appt-task-appointments-section} is the same as the
4901 schedule section specified in @code{planner-appt-schedule-section} (by
4902 default @code{"Schedule"}), the default formatting function adds a
4903 @samp{#} to the description so that one can visually distinguish
4904 appointments from the task list from those that have been added to the
4907 @node Schedule-based Appointments, Viewing Appointments, Task-based Appointments, Appointments
4908 @comment node-name, next, previous, up
4909 @subsubsection Schedule-Based Appointments
4910 @cindex appointments, schedule-based
4911 @cindex schedule-based appointments
4913 Some scheduled tasks require reminders, others don't. In this
4919 9:00 | 12:00 | Read Simmel's Philosophy of Money
4920 @@12:45 Do Something Else
4921 @@13:00 | 14:00 | lunch
4922 @@14:30 | | Meet jrs to discuss his dissertation
4923 @@16:00 Test Society seminar
4928 those that have an @@ prefix will be added to the appointment
4929 reminder list; the others will not. The formats that are
4930 recognized are fairly flexible, as you can see from the example.
4932 If you change your schedule, you can update the appointment list
4936 M-x planner-appt-update
4939 @noindent You can also have the schedule sorted as part of the update,
4940 if you have this in your configuration:
4943 (setq planner-appt-sort-schedule-on-update-flag t)
4947 @c @strong{Cyclical Entries}
4948 @unnumberedsubsubsec Cyclical Entries
4949 @cindex appointments, cyclic schedule entries
4951 You can also have cyclical schedule entries(@pxref{Cyclic Tasks}) if you
4955 (planner-appt-schedule-cyclic-insinuate)
4958 @noindent to your configuration.
4960 If you put an entry in your cyclical task file like this
4963 Friday @@12:45 | 13:45 | Staff Meeting
4967 then it will appear in your schedule every Friday, and an
4968 appointment alert will be set up.
4970 @node Viewing Appointments, Appointment Updating on Save, Schedule-based Appointments, Appointments
4971 @comment node-name, next, previous, up
4972 @subsubsection Viewing Appointments
4973 @cindex appointments, viewing
4975 The command @command{planner-appt-show-alerts} will show all appointment
4976 alerts currently scheduled.
4978 @subheading Functions
4980 There are two commands that show appointments in the future; the one
4981 displays them in a pop-up buffer, the other puts the information into
4982 the current day page.
4984 @deffn {Command} planner-appt-forthcoming-display &optional days
4985 Display a buffer of appointments for today and the next
4986 @var{days}. Optional prefix argument @var{days} is the number of days
4987 ahead to look. Its default value is defined by
4988 @code{planner-appt-forthcoming-days}.
4991 @deffn {Command} planner-appt-forthcoming-update-section &optional days
4992 In today's plan page, add or update a list of forthcoming
4993 appointments. Optional prefix argument @var{days} is the number of
4994 days ahead to look. Its default value is defined by
4995 @code{planner-appt-forthcoming-days}. The section heading to use is
4996 defined by @code{planner-appt-forthcoming-appt-section}.
5001 @defopt planner-appt-forthcoming-days
5002 The number of days to look ahead for forthcoming appointments. The
5003 default value is seven days.
5006 @defopt planner-appt-forthcoming-appt-section
5007 The name of the section to use for inserting a list of forthcoming
5008 appts. The default value is @code{"Forthcoming Appointments"}.
5011 @defopt planner-appt-forthcoming-show-day-names-flag
5012 When non-nil (the default), day names will be shown in forthcoming
5016 @defopt planner-appt-forthcoming-repeat-date-string
5017 String to insert for repeated dates.
5019 When there are multiple appointments for a date, the date is inserted
5020 in the first appointment and the others have this string in their date
5023 If the string consists of anything other than whitespace, then a link
5024 to the day page for the appoinment is created.
5027 @defopt planner-appt-forthcoming-look-at-cyclic-flag
5028 When non-nil, find forthcoming appointments in the cyclic diary file
5029 (@pxref{Cyclic Tasks}) as well as in plan pages. Default is @samp{t}.
5032 @node Appointment Updating on Save, Appointment and Calendar Integration, Viewing Appointments, Appointments
5033 @comment node-name, next, previous, up
5034 @subsubsection Appointment Updating on Save
5035 @cindex appointments, updating on save
5039 @defopt planner-appt-update-appts-on-save-flag
5040 When non-nil, update appointment reminders whenever today's plan page is
5041 saved. Default value is @samp{nil}.
5044 @node Appointment and Calendar Integration, Appointment Hooks, Appointment Updating on Save, Appointments
5045 @comment node-name, next, previous, up
5046 @subsubsection Appointment and Calendar Integration
5048 Not strictly part of appointment handling, but if one isn't using
5049 the diary, marking dates with plan pages seems to make sense.
5051 @subheading Functions
5053 @defun planner-appt-calendar-insinuate
5054 Add a hook to diary display so that dates in the calendar that have day
5055 pages are highlighted
5058 @node Appointment Hooks, , Appointment and Calendar Integration, Appointments
5059 @comment node-name, next, previous, up
5060 @subsubsection Appointment Hooks
5064 @defvr {Hook} planner-appt-update-hook
5065 Hook run after @code{planner-appt-update} has updated the appointment
5069 @node Timeclock, schedule.el, Appointments, Scheduling and Time
5070 @comment node-name, next, previous, up
5071 @subsection Timeclock
5072 @cindex @file{planner-timeclock.el}, using
5073 @cindex @file{planner-timeclock-summary.el}, using
5074 @cindex @file{planner-timeclock-summary-proj.el}, using
5075 @cindex timeclock, using Planner with
5077 This module allows you to clock in and clock out of your projects
5078 (@pxref{Time Intervals, , , Emacs, GNU Emacs Manual}) You can also
5079 generate reports with the @code{<timeclock-report>} tag. You may want to
5080 read the ``Keeping Track of Time'' page to see how you can use
5081 planner-timeclock to produce detailed reports;
5082 @xref{Keeping Track of Time}.
5084 @file{timeclock.el} is part of GNU Emacs. If you are using XEmacs,
5085 please use the version of @file{timeclock.el} that comes with Planner in
5086 the @file{contrib} directory.
5088 With @file{planner-timeclock.el} loaded,
5089 @command{planner-task-in-progress} clocks in a task. To clock out,
5090 use @command{planner-task-done} or @command{timeclock-out}.
5092 @file{planner-timeclock.el} defines the following keybindings:
5095 @item @kbd{C-c C-i}: @code{planner-task-in-progress}.
5096 @item @kbd{C-c C-o}: @code{timeclock-out}.
5097 @item @kbd{C-c C-T C-i}: @code{planner-timeclock-in}. (XEmacs)
5098 @item @kbd{C-c C-T C-o}: @code{timeclock-out}. (XEmacs)
5099 @item @kbd{C-c C-S-t C-i}: @code{planner-timeclock-in}. (GNU Emacs)
5100 @item @kbd{C-c C-S-t C-o}: @code{timeclock-out}. (GNU Emacs)
5103 If you use @code{timeclock} a lot, you may also be interested in
5104 Dryice Liu's @file{planner-timeclock-summary.el}, which produces
5105 timeclock reports for planner files.
5107 Here is a sample report:
5110 Project | Time| Ratio| Task
5111 PlannerMaintenance | 0:03:58| 1.1%| Merge doc patch
5112 | 0:17:09| 5.0%| Track down subdirectories
5113 | 0:18:11| 5.3%| Merge planner-timeclock-summary-proj.el
5114 Total: | 0:39:18| 11.4%|
5115 JapanCaseStudy | 2:37:56| 45.6%| Prototype search result page
5116 | 0:31:50| 9.2%| Update design documents
5117 Total: | 3:09:46| 54.8%|
5118 ChristmasLetter | 1:46:37| 30.8%| Write and send my Christmas letters
5119 Total: | 1:46:37| 30.8%|
5120 LinuxPeople | 0:10:29| 3.0%| Send questions for Linux in Education
5121 Total: | 0:10:29| 3.0%|
5124 If you add @code{(require 'planner-timeclock-summary)} to your
5125 @file{~/.emacs}, you can then use it in two ways.
5129 @item Display a temporary buffer
5131 Call @code{planner-timeclock-summary-show} and Emacs will ask you which
5132 day's summary do you want. Choose the date as anywhere else of
5133 Emacs planner, and a tempory buffer will be displayed with the
5134 timeclock summary of that day.
5136 To review tasks over a date range, use
5137 @code{planner-timeclock-summary-show-range}. You can use a regexp or a
5138 function to filter tasks by calling
5139 @code{planner-timeclock-summary-show-range-filter}.
5141 @item Rewrite sections of your planner
5143 Choose this approach if you want timeclock summary to be in their
5144 own section and you would like them to be readable in your plain
5145 text files even outside Emacs. Caveat: The timeclock summary
5146 section should already exist in your template and will be rewritten
5147 when updated. Tip: Add @code{planner-timeclock-summary-section}
5148 (default: @samp{"Timeclock"}) to your @code{planner-day-page-template}.
5150 To use, call @code{planner-timeclock-summary-update} in the planner
5151 day page to update the section. If you want rewriting to be
5152 automatically performed, call
5153 @code{planner-timeclock-summary-insinuate} in your @file{.emacs} file.
5156 @file{planner-timeclock-summary-proj.el} produces task / time
5157 breakdowns on plan pages. Reports are of the form:
5165 To use, add @code{(require 'planner-timeclock-summary)} to your
5166 @file{~/.emacs}. Call @code{planner-timeclock-summary-proj-current}
5167 from a project page. The report is inserted at the current position in
5168 the buffer. The function @code{planner-timeclock-summary-proj-section}
5169 does the same but the report is inserted inside a section called
5172 @node schedule.el, , Timeclock, Scheduling and Time
5173 @comment node-name, next, previous, up
5174 @subsection @file{schedule.el}
5175 @cindex @file{planner-schedule.el}, using
5176 @cindex @file{schedule.el}, using Planner with
5178 @file{planner-schedule.el} allows you to project task completion time.
5179 Tasks should be of the form:
5182 #A0 _ 2h Do something
5183 #B0 _ 1h30m Do something
5184 #B0 _ 2d Do something
5185 #B0 _ 2w Do something
5186 #B0 _ 10s Do something
5188 s: seconds, m: minutes, h: hours, d: days, w: weeks
5191 @file{schedule.el} is included with Planner in the @file{contrib}
5192 directory, but you can alternatively get it from
5193 @url{http://www.newartisans.com/johnw/Emacs/schedule.el} if desired.
5195 @file{schedule.el} provides a single Lisp function,
5196 @code{schedule-completion-time}. It takes an Emacs time object and a
5197 quantity of seconds. It returns an Emacs time object that represents
5198 when the given number of seconds will be completed, assuming that work
5199 can only be done during work hours.
5201 The available work hours are affected by several factors:
5206 If @file{timeclock.el} is being used, the amount of time left in the
5207 current work day (@code{timeclock-workday-remaining})
5208 (@pxref{Time Intervals, , , Emacs, GNU Emacs Manual})
5211 The amount of time in each work day (@code{schedule-workday})
5214 The definition of a work week (@code{schedule-week})
5217 Any holidays defined in the Emacs calendar
5218 (@pxref{Holidays, , , Emacs, GNU Emacs Manual})
5221 Any appointments in the Emacs diary
5222 (@pxref{Appointments, , , Emacs, GNU Emacs Manual})
5226 Taking all of the ``block out'' periods into account,
5227 @code{schedule-completion-time} will compute when the given number of
5228 seconds will be done, based on your current definitions of time
5231 As an example, here's a function which, given a list of durations
5232 in seconds, will return a list of completion times starting from
5237 (defun compute-completion-times (&rest durations)
5238 ``Compute completion times for a list of DURATIONS (in seconds).''
5239 (let ((now (current-time)))
5243 (setq now (schedule-completion-time now dura))))
5248 To call this function, do:
5252 (compute-completion-times 3600 7200 3600)
5258 @file{planner-schedule.el} defines the following keybindings:
5260 @kbd{C-c RET} is bound to @command{planner-schedule-show-end-project}.
5261 @kbd{C-c C-m} is also bound to
5262 @command{planner-schedule-show-end-project}.
5264 In XEmacs, @command{planner-schedule-show-end-project} is bound to
5265 @kbd{C-c C-T c-e} and @kbd{C-c C-S-t C-e}.
5267 @subheading Functions
5269 @file{planner-schedule.el} defines the following interactive
5272 @defun planner-schedule-show-end-project
5273 Display the estimated project completion time.
5276 @file{schedule.el} does not define any interactive functions, or
5279 @node Finances, Contacts and Conversations, Scheduling and Time, Managing Your Information
5280 @comment node-name, next, previous, up
5284 Currently, Planner provides one module dedicated to tracking your
5285 finances. This module works with a program called Ledger.
5288 * Ledger:: Personal finances: planner-ledger.el
5291 @node Ledger, , Finances, Finances
5292 @comment node-name, next, previous, up
5295 @cindex @file{planner-ledger.el}, using
5296 @cindex @file{ledger}, using Planner with
5298 @file{planner-ledger.el} provides integration between planner and John
5299 Wiegley's ledger accounting program, which can be found at
5300 @url{http://newartisans.com/johnw/ledger.tar.gz}.
5302 To use planner-ledger to insert a ledger balance overview and a list
5303 of pending transactions into planner day pages, make sure that your
5304 day page includes sections that match
5305 @code{planner-ledger-balance-regexp} and
5306 @code{planner-ledger-pending-regexp}. Example:
5313 ** Pending transactions
5319 You can manually update ledger sections with the
5320 @command{planner-ledger-insert-maybe} command.
5322 You can also automatically update ledger sections with the following
5326 (add-hook 'planner-goto-hook 'planner-ledger-insert-maybe)
5329 You can create ledger entries from specially-formatted tasks using
5330 @command{planner-ledger-add-entry-from-task}. Tasks should be of the
5331 form @samp{payment due: payee, amount [comment]}. Example:
5334 #A1 _ payment due: foobar, $1000.00 some comment here
5335 #A2 _ payment due: baz, 1000.00
5340 @defopt planner-ledger-balance-accounts
5341 List of accounts to be included or excluded from the balance overview.
5342 @samp{+} includes all matching accounts, and @samp{-} excludes
5343 matching accounts. See the documentation for
5344 @command{ledger-run-ledger} for more details.
5347 @defopt planner-ledger-balance-regexp
5348 Regular expression matching section for ledger balance. Do not store
5349 other data in this section, as it will be overwritten.
5352 @defopt planner-ledger-pending-regexp
5353 Regular expression matching section for ledger balance. Do not store
5354 other data in this section, as it will be overwritten.
5357 @defopt planner-ledger-payment-task-regexp
5358 Regular expression matching special ledger tasks.
5361 @subheading Functions
5363 @defun planner-ledger-insert-maybe
5364 Update any ledger sections on the current page.
5367 @defun planner-ledger-add-entry-from-task
5368 Create a ledger entry based on the task at point. Task should match
5369 @code{planner-ledger-payment-task-regexp}.
5372 @node Contacts and Conversations, Tracking Research and Resources, Finances, Managing Your Information
5373 @comment node-name, next, previous, up
5374 @section Contacts and Conversations
5376 @cindex conversations
5378 Planner has two modules available for keeping track of contact and
5379 conversation information. The first uses the Big Brother Database
5380 (BBDB), and the second uses Emacs Relay Chat (ERC). BBDB is a full
5381 contact database. ERC is a client for chatting online on Internet Relay
5382 Chat (IRC) networks. The ERC module for Planner will help you keep
5383 track of online conversations you have if you use ERC for those
5384 conversations, but does not by itself store contact information other
5385 than the time you had the conversation, the network and channel you were
5386 on when you had it, and maybe who you had it with. If you are looking
5387 for a way to manage your full address book, then @file{planner-bbdb.el}
5388 in combination with BBDB is what you are looking for.
5391 * BBDB:: Contacts: planner-bbdb.el
5392 * Emacs Relay Chat:: Internet Relay Chat: planner-erc.el
5395 @node BBDB, Emacs Relay Chat, Contacts and Conversations, Contacts and Conversations
5396 @comment node-name, next, previous, up
5398 @cindex @file{planner-bbdb.el}, using
5399 @cindex BBDB, using Planner with
5401 @file{planner-bbdb.el} allows you to refer to your contacts easily
5402 from within a planner page. @inforef{Top, the BBDB Manual, bbdb}.
5404 @samp{[[bbdb://Sacha.*Chua][Sacha]]}, for example, will be linked to
5405 the blog, web or net fields of the first matching BBDB record.
5407 @file{planner-bbdb.el} does not define any interactive functions, or
5410 @node Emacs Relay Chat, , BBDB, Contacts and Conversations
5411 @comment node-name, next, previous, up
5412 @subsection Emacs Relay Chat
5413 @cindex @file{planner-erc.el}, using
5414 @cindex ERC, using Planner with
5415 @cindex Emacs Relay Chat, using Planner with
5416 @cindex IRC, using Planner with
5417 @cindex Internet Relay Chat, using Planner with
5419 To use planner-erc, place @file{planner-erc.el} in your load path
5420 and add this to your @file{.emacs} (or @file{_emacs}):
5424 (require 'planner-erc)
5428 IRC URLs may be of the following forms.
5431 irc://server/nick,isnick
5432 irc://server/#channel
5436 Annotations will be in the following forms.
5439 [[irc://server/nick,isnick][Chat with nick on server#channel]]
5440 [[irc://server/nick,isnick][Chat with nick on server]]
5441 [[irc://server/#channel][Chat on server#channel]]
5442 [[irc://server][Chat on server]]
5445 @file{planner-erc.el} does not define any interactive functions, or
5448 @node Tracking Research and Resources, Tracking Development, Contacts and Conversations, Managing Your Information
5449 @comment node-name, next, previous, up
5450 @section Tracking Research and Resources
5452 Planner provides three modules for keeping track of information
5453 involving three specific tools: w3m, BibTeX, and @file{bookmark.el}.
5456 * W3m:: Web browser: planner-w3m.el
5457 * BibTeX:: Bibliographies: planner-bibtex.el
5458 * Bookmark:: Bookmarks: planner-bookmark.el
5461 @node W3m, BibTeX, Tracking Research and Resources, Tracking Research and Resources
5462 @comment node-name, next, previous, up
5464 @cindex @file{planner-w3m.el}, using
5465 @cindex w3m, using Planner with
5467 This module allows you to create tasks from a w3m buffer.
5469 @file{planner-w3m.el} does not define any interactive functions, or
5472 @node BibTeX, Bookmark, W3m, Tracking Research and Resources
5473 @comment node-name, next, previous, up
5475 @cindex @file{planner-bibtex.el}, using
5477 BibTeX URLs are of the form @samp{bibtex:file/name:key}.
5479 @file{planner-bibtex.el} does not define any interactive functions.
5481 @node Bookmark, , BibTeX, Tracking Research and Resources
5482 @comment node-name, next, previous, up
5483 @subsection Bookmark
5485 @cindex @file{bookmark.el}, using Planner with
5486 @cindex @file{planner-bookmark.el}, using
5488 @file{planner-bookmark.el} uses the @file{remember} package to create a
5489 note whenever you create a bookmark (see @inforef{Bookmarks, Bookmarks,
5490 Emacs}). For more information about @file{remember}, please check out
5494 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} -
5497 @uref{http://sacha.free.net.ph/notebook/doc/dev/remember/remember.html}
5498 - Online info documentation
5501 Configure remember according to the instructions in
5502 @file{remember-planner.el} so that notes are saved to your planner
5505 @defopt planner-bookmark-take-note-after-set-bookmark-flag
5506 Non-nil means show a @code{remember} buffer after setting a new
5510 When you create a bookmark, Emacs will open a buffer for your notes.
5511 @kbd{C-c C-c} saves the buffer to today's page. If you don't want to
5512 save a note, you can kill the buffer.
5514 Bookmark URLs are of the form @samp{bookmark://bookmark-name}.
5516 @file{planner-bookmark.el} does not define any interactive functions.
5518 @node Tracking Development, , Tracking Research and Resources, Managing Your Information
5519 @comment node-name, next, previous, up
5520 @section Tracking Development
5521 @cindex version control, using Planner with
5523 Planner has three modules geared toward programmers. Two modules deal
5524 with version control and integrating information from those projects
5525 into the planner page. One module deals with the Gnats bug-tracking
5529 * Log Edit:: Changelogs: planner-log-edit.el
5530 * PSVN:: svn changesets: planner-psvn.el
5531 * XTLA:: TLA changesets: planner-xtla.el
5532 * Gnats:: Gnats: The GNU bug reporting system
5535 @node Log Edit, PSVN, Tracking Development, Tracking Development
5536 @comment node-name, next, previous, up
5537 @subsection Log Edit
5538 @cindex cvs, using Planner with
5539 @cindex @file{planner-log-edit.el}, using
5540 @cindex version control, using Planner with
5542 This module allows you to automatically record CVS (and VC) commits
5545 You can load the module with @code{(require 'planner-log-edit)}. When
5546 you load the module, @code{planner-log-edit-add-note} will be added to
5547 @code{log-edit-done-hook}. A note containing the text of the commit
5548 and optionally a list of modified files will be added to today's page
5549 if you use the the Emacs version control interface. (@pxref{Version
5550 Control, , , Emacs, GNU Emacs Manual})
5554 @defopt planner-log-edit-include-files-flag
5555 Non-nil means include a list of committed files in the note.
5558 @defopt planner-log-edit-notice-commit-function
5559 Non-nil means include a list of committed files in the note. If you
5560 want to enable this feature for some projects but not for others, set
5561 this to a function that returns t only for the commits you want to
5565 @file{planner-log-edit.el} does not define any interactive functions.
5567 @node PSVN, XTLA, Log Edit, Tracking Development
5568 @comment node-name, next, previous, up
5571 @cindex @file{planner-psvn.el}, using
5572 @cindex Subversion, integration with
5574 This module enables you to refer to your Subversion (svn) changesets
5575 easily from within a Planner page, and to have your svn commits recorded
5576 automatically as notes in your planner.
5578 You must also have @file{psvn.el}, which is often packaged with
5579 Subversion in GNU/Linux distributions.
5581 You can then load the module by adding @code{(require 'planner-psvn)} to
5582 your @file{~/.emacs}.
5584 Once the module is loaded, Planner will pick up annotation information
5585 from any psvn *svn-log-view* buffer. If you create a task or note while
5586 in such a buffer, that task will have a hyperlink you can follow to
5587 return to the changeset later.
5589 These hyperlinks are of the form
5590 @samp{psvn://http://my.svn-repos.at/svn/project1/trunk@@39}
5592 Additionally, you can have notes for your commits automatically
5593 generated. Set @var{planner-psvn-log-edit-notice-commit-function} to t
5596 By default, these commit notes will include a list of the files
5597 modified. If you would prefer to have this list not included, set
5598 @var{planner-psvn-log-edit-include-files-flag} to nil.
5600 @node XTLA, Gnats, PSVN, Tracking Development
5601 @comment node-name, next, previous, up
5604 @cindex @file{planner-xtla.el}, using
5606 This module allows you to refer to changesets in Tom Lord's Arch (tla)
5607 version control system. You can load the module with @code{(require
5608 'planner-xtla)}. When you load the module, you can create tasks from
5609 XTLA windows by positioning point on a revision.
5611 XTLA URLs are of the form
5612 @samp{xtla://miles@@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-19}
5614 @file{planner-xtla.el} does not define any interactive functions.
5616 @node Gnats, , XTLA, Tracking Development
5617 @comment node-name, next, previous, up
5621 @cindex @file{planner-gnats.el}, using
5622 @cindex bug reports, tracking
5624 @file{planner-gnats.el} provides support for the GNU problem report
5625 management system Gnats. This module allows you to refer to problem
5626 reports using hyperlinks.
5628 Configure your Emacs for Gnats access, then add @samp{(require
5629 'planner-gnats)} to your @file{.emacs}. You can then create tasks from
5630 Gnats edit or view buffers.
5632 To add keybindings to Gnats, use @samp{(planner-gnats-insinuate)}.
5634 Gnats URLs are of the form @samp{gnats:pr-number}.
5636 @file{planner-gnats.el} does not define any interactive functions.
5638 @node Advanced Configuration, Reference Material, Managing Your Information, Top
5639 @comment node-name, next, previous, up
5640 @chapter Advanced Configuration
5641 @cindex configuration, advanced
5644 * Customizing Your Day Pages:: Change your templates
5645 * Variables to Customize:: Change various aspects of Planner behavior
5646 * Ideas for Other Keybindings:: Add to and change the default keybindings
5649 @node Customizing Your Day Pages, Variables to Customize, Advanced Configuration, Advanced Configuration
5650 @comment node-name, next, previous, up
5651 @section Customizing Your Day Pages
5653 With the variable @code{planner-day-page-template}, you can define how
5654 you want any newly created day planner pages to look.
5656 You might want to include a section for your diary entries. For how to
5657 do this, see @ref{Diary}.
5659 You can add interactive Lisp buttons with the @file{planner-lisp.el}
5660 module. (@pxref{Interactive Lisp})
5662 Your @code{planner-day-page-template} can also include @samp{|<lisp>|}
5665 For more complex day pages, you can set
5666 @code{planner-day-page-template} to a function that will be called
5667 from an empty day page buffer. The function should initialize the
5668 contents of the day page.
5670 @node Variables to Customize, Ideas for Other Keybindings, Customizing Your Day Pages, Advanced Configuration
5671 @comment node-name, next, previous, up
5672 @section Variables to Customize
5673 @cindex customize, variables to
5674 @cindex variables, customization of
5675 @cindex configuration, advanced, variables
5677 If you want to change @code{planner-directory} and some other
5678 variables, either use Customize (@kbd{M-x customize-group RET planner
5679 RET}) or use @code{setq}. An example of the latter follows.
5682 (setq planner-directory "~/Plans")
5685 Other user options are:
5687 @vindex planner-use-day-pages
5688 @defopt planner-use-day-pages
5689 If you really don't like day pages, you can set this variable to nil
5690 and you won't be prompted for dates for tasks (and notes, if using
5691 @file{remember-planner}).
5694 @vindex planner-use-plan-pages
5695 @defopt planner-use-plan-pages
5696 If you really don't like plan pages, you can set this variable to nil
5697 and you won't be prompted for plan pages for tasks (and notes, if
5698 using @file{remember-planner}).
5701 @vindex planner-mode-hook
5702 @defopt planner-mode-hook
5703 List of functions to run after @code{planner-mode} is initialized.
5706 @vindex planner-tasks-file-behavior
5707 @defopt planner-tasks-file-behavior
5708 This variable controls what happens to files Planner opens by itself.
5709 If your tasks are associated with plan pages, the plan pages are
5710 updated whenever a task is rescheduled. This could lead to a lot of
5711 open buffers as Planner applies updates to all linked files.
5712 By default, Planner is configured to do nothing.
5713 A value of @samp{save} means save but do not close buffers, and a
5714 value of @samp{nil} means do not save any of the buffers.
5717 @vindex planner-add-task-at-end-flag
5718 @defopt planner-add-task-at-end-flag
5719 This variable controls where new tasks are created. Non-nil means
5720 create tasks at the bottom of the first task block. If you set this
5721 to non-nil, new tasks will be listed in order of creation (oldest).
5722 Tasks carried over from previous days will appear at the bottom of the
5725 Nil means create tasks at the top of the first task block.
5726 Carried-over tasks and newly created tasks are prominently placed on
5727 top of the list of tasks for the day.
5730 @vindex planner-default-page
5731 @defopt planner-default-page
5732 Default page for created tasks. This is used as the initial value for
5733 tasks. After you create a task, it will be set to the previous page
5737 @vindex planner-hide-task-status-when-highlighting
5738 @defopt planner-hide-task-status-when-highlighting
5739 Font-locking for tasks may be enough for you to determine status and
5740 priority. Set this to non-nil if you want to hide the status marker
5741 and rely on font-locking instead.
5744 @vindex planner-create-task-hook
5745 @defopt planner-create-task-hook
5746 Functions run after creating a task. @code{planner-id} hooks into
5750 @vindex planner-expand-name-favor-future-p
5751 @defopt planner-expand-name-favor-future-p
5752 If non-nil, partial dates (ex: @kbd{2} or @kbd{5.2}) are completed to
5753 dates in the future instead of using the current year and month.
5756 @vindex planner-task-dates-favor-future-p
5757 @defopt planner-task-dates-favor-future-p
5758 Like @code{planner-expand-name-favor-future-p}, but only for tasks.
5761 @vindex planner-publish-dates-first-p
5762 @defopt planner-publish-dates-first-p
5763 Non-nil means list day pages first in the planner index.
5766 @node Ideas for Other Keybindings, , Variables to Customize, Advanced Configuration
5767 @comment node-name, next, previous, up
5768 @section Ideas for Other Keybindings
5769 @cindex keybindings, customization of
5770 @cindex configuration, advanced, keybindings
5771 @cindex customize, keybindings to
5773 By default and for backward compatibility, the following operations
5774 do not have keybindings, and are only accessible from the Planner
5780 @code{planner-copy-or-move-region}
5783 @code{planner-delete-task}
5786 @code{planner-task-delegated}
5789 @code{planner-task-pending}
5792 @code{planner-task-open}
5795 @code{planner-renumber-tasks}
5799 You may find it easier to install keybindings for those operations by
5800 inserting the following in your @file{.emacs} (or @file{_emacs}).
5801 Note: This changes some of the default keybindings for Planner.
5804 (planner-install-extra-task-keybindings)
5807 If you install the extra task keybindings, your keybindings will
5813 @kbd{C-c C-t} will be unbound from the default and will serve as the
5814 prefix for the other task keybindings.
5817 @kbd{C-c C-t C-t}: @code{planner-create-task-from-buffer}.
5820 @kbd{C-c C-t C-k}: @code{planner-delete-task}.
5823 @kbd{C-c C-t C-u}: @code{planner-update-task}.
5826 @kbd{C-c C-t C-c}: @code{planner-copy-or-move-task}.
5829 @kbd{C-c C-t C-S-c}: @code{planner-copy-or-move-region}.
5832 @kbd{C-c C-t C-x}: @code{planner-task-done}.
5835 @kbd{C-c C-t C-S-x}: @code{planner-task-cancelled}.
5838 @kbd{C-c C-t C-d}: @code{planner-task-delegated}.
5841 @kbd{C-c C-t C-p}: @code{planner-task-pending}.
5844 @kbd{C-c C-t C-o}: @code{planner-task-in-progress}.
5847 @kbd{C-c C-t C-r}: @code{planner-raise-task}.
5850 @kbd{C-c C-t C-l}: @code{planner-lower-task}.
5853 @kbd{C-c C-t C-n}: @code{planner-renumber-tasks}.
5857 Other keybindings can be configured by adding this to your
5858 @file{.emacs} (or @file{_emacs}):
5861 (planner-install-extra-context-keybindings)
5864 This will set up the following keybindings:
5869 @kbd{shift up} @code{planner-move-up}
5872 @kbd{shift down} @code{planner-move-down}
5875 @kbd{shift right} @code{planner-jump-to-link}
5879 @node Reference Material, Getting Help, Advanced Configuration, Top
5880 @comment node-name, next, previous, up
5881 @chapter Reference Material
5884 * Keeping Track of Time::
5885 * Other Interactive Functions::
5886 * Planner Keybindings:: Default keybindings for Planner
5887 * Sample Configuration Files::
5890 @node Keeping Track of Time, Other Interactive Functions, Reference Material, Reference Material
5891 @section Keeping Track of Time
5893 One of the coolest things you can do with Planner is keep track of how
5894 much time you spend not only on projects but even on particular tasks.
5895 @file{planner-timeclock.el} makes it as easy and natural as marking a
5896 task as in progress, postponed, or done. This can help you determine
5897 just how much time you spend working each day. If you add estimates to
5898 your task descriptions, you'll also be able to use this information to
5899 improve your time estimation skills.
5901 Here's how you can keep track of the time you
5904 Then the fun began. I wanted to see if I could match my estimates.
5905 Before I started working on a task, I used @kbd{C-c TAB} to mark it
5906 @code{in progress} and start the clock. If I decided to work on
5907 something else, I used @kbd{C-c TAB} to clock out of the previous task
5908 and clock into the new one.
5910 When I finished it, I used @kbd{C-c C-x} (@code{planner-task-done}) to
5911 mark it completed and automatically clock out. This is not yet done
5912 for cancelled tasks, so I clocked out of those manually with @kbd{C-c
5913 C-o} (@code{timeclock-out}). I also clocked out whenever I caught
5914 myself being distracted so that the totals wouldn't include the time I
5915 spent chatting on #emacs or checking out del.icio.us links. =) At the
5916 end of the day, I used
5917 @code{planner-timeclock-summary-show-range-filter} to show me the time
5918 elapsed for all of the tasks I'd worked on over the past two days.
5919 Here's the report for that project, edited to reflect how it looks on
5920 my screen and annotated with comments:
5923 Timeclock summary report for 2004.12.28 - 2004.12.29
5925 Project | Time| Ratio| Task
5926 JapanProject| 0:23:17| 3.6%| Translate javadoc comment for Messages.java
5927 | 0:33:48| 5.3%| Translate javadoc comment for LoginAction.java
5928 | 1:54:07| 17.8%| Study Struts in Japanese
5929 | 0:46:08| 7.2%| Add javadoc tags for input, output and forwards
5930 | 1:03:48| 9.9%| Help review code
5931 | 0:04:14| 0.7%| Import todo list
5932 | 0:00:37| 0.1%| 2min Fix Menu Action's unnecessary code - delegated
5933 | 0:01:01| 0.2%| 2min Remove unnecessary list in UserRemoveSetupAction - cancelled
5934 | 0:02:10| 0.3%| 2min Remove hard-coded database path from MenuAction
5935 | 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. ...
5936 | 0:07:32| 1.2%| 5min Add a method that returns the validity of a user in MUserPeer.
5937 | 0:08:28| 1.3%| 5min Fix indentation
5938 | 0:03:52| 0.6%| 10min Fix UserPeer so that it doesn't get null pointer exceptions
5939 | 0:04:34| 0.7%| 5min Add current password field in user_modify page
5940 | 0:21:56| 3.4%| 15min Make a super class for our service classes that will receive the database connection. (cancelled)
5941 | 0:06:05| 0.9%| 10min Remove hard-coded constants from the Logic classes
5942 | 0:10:55| 1.7%| 10min Move logic from UserBean.checkPassword to UserListLogic
5943 | 0:01:20| 0.2%| 20min Guard against null pointer exceptions in peer classes
5944 | 0:04:57| 0.8%| 10min Instead of displaying uneditable data with bean:write, just disable the html:text element
5945 | 0:25:03| 3.9%| 10min Deploy 10:00 version
5946 | 0:04:46| 0.7%| 5min Separate the configuration file of database and system into another uninternationalized property file.
5947 | 2:09:48| 20.2%| 1h Decide on a naming convention for localized messages and update files
5948 | 0:00:07| 0.0%| 20min Explain what is happening in UserModifyAction's nested ifs - pending
5949 | 1:50:23| 17.2%| 2h Write Javadoc comments in English and Japanese to explain bean structure
5950 | 0:04:19| 0.7%| 2h Write Javadoc comments in English and Japanese to explain peer operations (pending)
5951 | 0:05:40| 0.9%| 20min Make a factory class for the database - pending
5952 Total: | 10:41:41|100.0%|
5954 Day began: 13:03:58, Day ended: 20:51:46
5955 Time elapsed: 31:47:48, Time clocked: 10:41:41
5956 Time clocked ratio: 33.6%
5959 The time record isn't perfect. I cancelled some tasks after thinking
5960 about them a little and did some tasks simultaneously. Sometimes I
5961 didn't notice that I was getting distracted, too. Still, having all of
5962 that time information neatly summarized made me realize a number of
5965 First, I goof off much less when I have a nice, broken-down task list
5966 in front of me. There's just something about knowing there's a five-
5967 or ten-minute hack you can get out of the way. I found myself looking
5968 forward to getting to the next task just to see if I could make my
5969 estimate. That said, seeing a five-minute task stretch and stretch due
5970 to unforeseen problems did make me a little nervous. I should probably
5971 just make generous estimates so that I don't end up with bugs because
5974 Second, I don't goof off as much as I thought I did, although there's
5975 still room for improvement. Yesterday's workday was 9:00 - 12:00, 1:00
5976 - 5:30--7.5 hours. Today was the last day of work, so cleaning and
5977 celebration interrupted my hacking at around 3:00--5 hours of work.
5978 According to my task list, 10:41/12:30 was productive work. Hmm. 1:49
5979 hours unclocked time when I was thinking or goofing off.
5980 planner-timeclock-summary-show for today reveals that I actually
5981 clocked 5:30 today, which means the goofing off happened yesterday.
5982 That makes sense; I remember a pretty long unclocked segment
5983 recuperating from Japanese overload. (This was before we came up with
5986 Third, keeping track of time is way, way cool even if you don't bill
5987 anyone for your time.
5989 Like the idea? It's easy to try out. Just add
5992 (require 'planner-timeclock)
5993 (require 'planner-timeclock-summary)
5996 to your ~/.emacs. If you want to try it out now, eval those statements
5997 in your Emacs session. After that, simply use @kbd{C-c TAB} to ``clock
5998 in'' a task before you start working on it and @kbd{C-c C-x}
5999 (@code{planner-task-done}) to mark it completed. @kbd{M-x
6000 planner-task-pending} also clocks out the current task if it was
6001 clocked in. To see a summary of how you spent your day, check out the
6002 different functions in @file{planner-timeclock-summary}.
6004 See @ref{Timeclock} for more details.
6008 @node Other Interactive Functions, Planner Keybindings, Keeping Track of Time, Reference Material
6009 @comment node-name, next, previous, up
6010 @section Other Interactive Functions
6012 With @file{planner.el} loaded, you can use any of the functions in this
6013 section by typing @kbd{M-x} followed by the name of the function. Many
6014 of these functions are also bound to keys.
6016 For a list of Planner keybindings, see @ref{Planner Keybindings}.
6018 They are listed in no particular order.
6020 @file{planner.el} defines the following interactive functions:
6023 @defun planner-create-high-priority-task-from-buffer
6024 Create a high priority task based on this buffer. Do not use this in
6025 LISP programs. Instead, set the value of
6026 @var{planner-default-task-priority} and call @code{planner-create-task}
6027 or @code{planner-create-task-from-buffer}.
6030 @defun defun planner-create-medium-priority-task-from-buffer
6031 Create a medium-priority task based on this buffer. Do not use this in
6032 LISP programs. Instead, set the value of
6033 @var{planner-default-task-priority} and call @code{planner-create-task}
6034 or @code{planner-create-task-from-buffer}.
6037 @defun planner-create-low-priority-task-from-buffer
6038 Create a high-priority task based on this buffer.
6039 Do not use this in LISP programs. Instead, set the value of
6040 @var{planner-default-task-priority} and call @code{planner-create-task} or
6041 @code{planner-create-task-from-buffer}.
6044 @defun planner-install-extra-context-keybindings
6045 Install extra context-sensitive keybindings. These keybindings
6046 conflict with @file{windmove.el}, but might be useful.
6049 @defun planner-narrow-to-section section &optional create
6050 Widen to the whole page and narrow to the section labelled
6051 @var{section}. If @var{create} is non-nil and the section is not found,
6052 the section is created. Return non-nil if @var{section} was found or
6056 @defun planner-save-buffers
6057 Save all planner-mode buffers.
6060 @defun planner-seek-to-first section
6061 Positions the point at the specified @var{section}, or @samp{Tasks} if
6065 @defun planner-save-buffers
6066 Save all planner buffers.
6069 @defun planner-calendar-insinuate
6070 This hooks Planner into Emacs Calendar (@pxref{Calendar/Diary, ,
6071 , Emacs, GNU Emacs Manual}).
6073 It adds special planner key bindings to @code{calendar-mode-map}.
6074 After this function is evaluated, you can use the following
6075 planner-related keybindings in @code{calendar-mode-map}:
6080 Jump to the planner page for the current day.
6083 Display the planner page for the current day.
6088 @defun planner-kill-calendar-files
6089 Remove planner files shown from Calendar (@pxref{Calendar/Diary, , ,
6090 Emacs, GNU Emacs Manual}).
6094 @defun planner-calendar-goto
6095 Goto the plan page corresponding to the calendar date
6096 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6099 @defun planner-calendar-show
6100 Show the plan page for the calendar date under point in another window
6101 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6104 @defun planner-calendar-select
6105 Return to @code{planner-read-date} with the date currently selected
6106 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6109 @defun planner-jump-to-link
6110 Jump to the item linked to by the current item.
6113 @defun planner-move-up
6114 Move a task up. You can use this to indicate that you will do a task
6115 before another one. On a note, go to the previous note. On a headline,
6116 go to the previous headline of the same depth.
6119 @defun planner-move-down
6120 Move down. You can use this to indicate that you will do a task after
6121 another one. On a note, go to the next note. On a headline, go to the
6122 next headline of the same depth.
6125 @node Planner Keybindings, Sample Configuration Files, Other Interactive Functions, Reference Material
6126 @comment node-name, next, previous, up
6127 @section Planner Keybindings
6128 @cindex keybindings, list
6130 In order to refresh and renumber all of your tasks according to their
6131 actual order in the buffer, simply save the file or call
6132 @kbd{M-x planner-renumber-tasks}.
6134 Here is a summary of the keystrokes available:
6139 Begin your planning session. This goes to the last day for which
6140 there is any planning info (or today if none), allowing you to review,
6141 and create/move tasks from that day.
6150 Mark the task as in progress or delegated.
6153 Mark the task as finished.
6156 Create a task associated with the current Wiki page. If you are on the
6157 opening line of a Note entry, it is assumed that the note itself is the
6161 Move or copy the current task to another date. If the current task is
6162 an original (meaning you are in the buffer where's defined, hopefully
6163 a planning page) then it will be copied, and the original task will
6164 also now point to the copy. If the current task is a copy, it will
6165 just be moved to the new day, and the original task's link will be
6169 Jump to today's task page. If you call
6170 @code{(planner-calendar-insinuate)}, typing @kbd{n} in the Emacs
6171 calendar (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) will jump
6172 to today's task page.
6175 @code{planner-task-done}
6178 @code{planner-task-in-progress}
6181 @code{planner-lower-task}
6184 @code{planner-raise-task}
6187 @code{planner-copy-or-move-task}
6190 @code{planner-create-task-from-buffer}
6193 This is a prefix command.
6196 @code{planner-goto-today}
6199 @code{planner-goto-most-recent}
6202 @code{planner-goto-tomorrow}
6205 @code{planner-goto-yesterday}
6208 @code{planner-goto-today}
6211 @code{planner-goto-next-daily-page}
6214 @code{planner-goto-previous-daily-page}
6221 @node Sample Configuration Files, , Planner Keybindings, Reference Material
6222 @comment node-name, next, previous, up
6223 @section Sample Configuration Files
6224 @cindex configuration, sample
6226 This section includes some sample configuration files. This way, once
6227 you've got the hang of the basics, you can see some different, more
6230 There is no One True Way to plan. Every person is different. We hope
6231 you'll find a good starting point among the example configurations
6232 below. If what you want to do does not perfectly fit under one of these
6233 examples, please post a description of the way you plan to our mailing
6234 list (@pxref{Getting Help}). We look forward to helping you customizing
6235 planner to fit your needs.
6238 * File Organization::
6239 * Bare-Bones Planning::
6240 * Bare-Bones Planning with Plan Pages::
6241 * Tasks on Plan Pages with Some Day Pages::
6242 * Hierarchical Tasks::
6245 @node File Organization, Bare-Bones Planning, Sample Configuration Files, Sample Configuration Files
6246 @subsection File Organization
6249 @item @strong{Tasks, schedule and notes on day pages.}
6251 By default, tasks, schedule entries and notes are filed on day pages.
6252 This makes it easy for you to see all the entries relevant to a single
6253 day without becoming overwhelmed with information. Unfinished tasks
6254 are carried over to the next day when you use @kbd{M-x plan}, so it's
6255 always kept up to date. Completed tasks are left on the day page you
6256 finished them on, which helps when reviewing one's progress and writing
6257 accomplishment reports.
6259 @item @strong{Cross-referenced with plan pages.}
6261 You can associate your tasks with projects either when you create the
6262 task or later, with @kbd{M-x planner-replan-task}. This makes it easy
6263 for you to see all the information associated with a particular
6264 project. If you use RememberMode to create notes, you will also be
6265 able to associate notes with a plan page.
6267 @item @strong{Just plan pages.}
6269 If your tasks don't usually have dates, you can turn day pages off by
6270 customizing @code{planner-use-day-pages}. If so, then all of your
6271 tasks and notes will be stored on the WelcomePage and/or a plan page.
6275 @node Bare-Bones Planning, Bare-Bones Planning with Plan Pages, File Organization, Sample Configuration Files
6276 @subsection Bare-Bones Planning
6278 You can keep all of your tasks, notes and schedules in a single file:
6279 WelcomePage. This is good for people who are used to storing all of
6280 their information in a flat text file. By storing your information in
6281 planner, you'll be able to take advantage of automatic hyperlinking to
6282 files and other resources. You can also sort your tasks by priority
6285 To set your system up for bare-bones planning, set the
6286 @code{planner-use-day-pages} variable to nil before loading planner.
6287 For example, you can put this in your @file{~/.emacs} (or @file{_emacs}):
6290 (setq planner-use-day-pages nil)
6291 (setq planner-default-page nil)
6295 When you create a task or note, planner will not prompt you for a
6296 date. If you press @key{RET} when prompted for a plan page, it will
6297 accept the default of nil, so no other plan pages will be used. All
6298 of your data will be kept in one file, which can then be easily backed
6301 You can use commands like @command{planner-create-task-from-buffer} to
6302 create tasks, or you can type tasks in manually. You can edit or
6303 delete anything in the page without having to update other files.
6305 @node Bare-Bones Planning with Plan Pages, Tasks on Plan Pages with Some Day Pages, Bare-Bones Planning, Sample Configuration Files
6306 @subsection Bare-Bones Planning with Plan Pages
6308 When you create a task or note, Planner.el can copy this to a plan
6309 page. Plan pages allow you to see an overview of all the data for a
6312 For convenience, the @command{planner-create-task-from-buffer} command
6313 prompts you for a plan page when you create a task.
6317 @node Tasks on Plan Pages with Some Day Pages, Hierarchical Tasks, Bare-Bones Planning with Plan Pages, Sample Configuration Files
6318 @subsection Tasks on Plan Pages with Some Day Pages
6320 If most of your tasks are associated with plan pages but you want to
6321 schedule some tasks on day pages, you can leave day pages on (default)
6322 and then write a function that turns off day pages. For example, the
6323 following code snippet turns off day pages for task creation from
6329 (defun my-planner-create-task-from-buffer ()
6330 "Call `planner-create-task-from-buffer', but without dates."
6332 (let ((planner-use-day-pages nil))
6333 (call-interactively 'planner-create-task-from-buffer)))
6336 @node Hierarchical Tasks, , Tasks on Plan Pages with Some Day Pages, Sample Configuration Files
6337 @subsection Hierarchical Tasks
6338 @cindex hierarchical tasks
6339 @cindex tasks, hierarchy of
6341 You can use @file{allout.el} or other modes for outlining to support
6342 hierarchical tasks in plan pages. No special support is needed.
6344 Tasks created by @command{planner-create-task-from-buffer} and
6345 @code{planner-create-task} are created in the @samp{* Tasks} section.
6346 If @code{planner-add-task-at-end-flag} is non-nil, tasks are added to
6347 the end of the first task block, else they are added to the beginning.
6348 You can then copy and paste tasks into your preferred hierarchy.
6349 Blank lines delimit blocks of tasks upon which automatic sorting is
6352 You can also type in tasks manually. You may find this approach faster
6353 when you are comfortable with planner.
6355 For example, a @file{LearnPlanner} plan page might contain the
6359 * Learn how to use planner.el
6363 #C0 _ Decide where to put Planner
6364 #C0 _ Download the archives
6370 #C0 _ Figure out how to add things to my load path
6371 #C0 _ Actually add it to my load path
6376 If you create tasks for the finest level of detail available at the
6377 moment, you can schedule them onto day pages with @kbd{C-c C-c}
6378 (@command{planner-copy-or-move-task}). Then you can use
6379 @command{planner-jump-to-link} to switch between the day page and the
6383 @node Getting Help, Acknowledgements, Reference Material, Top
6384 @comment node-name, next, previous, up
6385 @chapter Getting Help
6386 @cindex help, getting
6387 @cindex bugs, reporting
6389 After you have read this guide, if you still have questions about
6390 Planner, or if you have bugs to report, there are several places
6393 Planner has an official website at
6394 @url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}. It is a
6397 Bugs may be reported using the Planner Bug-Tracker at
6398 @url{http://gna.org/bugs/?group=planner-el}.
6400 Planner has three mailing lists.
6404 @item planner-el-announce
6405 Low-traffic list for planner-related announcements.
6407 You can join this mailing list (@email{planner-el-announce@@gna.org})
6408 using the subscription form at
6409 @url{http://mail.gna.org/listinfo/planner-el-announce/}. This
6410 mailing list is also available via Gmane (@url{http://gmane.org/}). The
6411 group is called @samp{gmane.emacs.planner.announce}.
6413 @item planner-el-discuss
6414 Discussion, bugfixes, suggestions, tips, and the like for Planner.
6415 This mailing list also includes the content of planner-el-announce.
6417 You can join this mailing list (@email{planner-el-discuss@@gna.org})
6418 using the subscription form at
6419 @url{http://mail.gna.org/listinfo/planner-el-discuss/}. This mailing
6420 list is also available via Gmane with the identifier
6421 @samp{gmane.emacs.planner.general}.
6423 @item planner-el-cvs
6424 Log messages for changes committed to Planner.
6426 You can join this mailing list (@email{planner-el-cvs@@gna.org}) using
6427 the subscription form at
6428 @url{http://mail.gna.org/listinfo/planner-el-cvs/}. This mailing list
6429 is also available via Gmane with the identifier
6430 @samp{gmane.emacs.planner.cvs}.
6434 You can also contact the maintainer of Planner, John Sullivan, at
6435 @email{john@@wjsullivan.net}, but it is better to use the other options.
6437 You can explore the relevant sections of the EmacsWiki.org:
6442 @url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}
6445 @url{http://www.emacswiki.org/cgi-bin/wiki/MuseMode}
6448 @url{http://www.emacswiki.org/cgi-bin/wiki/RememberMode}
6452 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
6453 contributors are frequently around and willing to answer your
6456 There is an Orkut community called PlannerMode.
6458 For issues relating to this documentation, please contact John
6459 Sullivan at @email{john@@wjsullivan.net}.
6461 @node Acknowledgements, GNU General Public License, Getting Help, Top
6462 @comment node-name, next, previous, up
6463 @chapter Acknowledgements
6472 John Sullivan volunteered to maintain Planner, and Michael Olson passed
6473 the maintainership on to him with the release of Planner 3.41.
6477 Michael Olson, Sacha Chua, and several others from the Planner community
6478 ported Planner to use Muse instead of emacs-wiki. Michael Olson became
6479 the maintainer of Planner.
6483 Damien Elmes handed EmacsWikiMode to Mark Triggs for a short period of
6484 time. Mark Triggs deferred to Sacha Chua as official maintainer of
6485 Planner. Sacha Chua volunteered to maintain RememberMode.
6486 Michael Olson became the maintainer of both emacs-wiki and Muse.
6490 Sacha Chua volunteered to maintain Planner. Damien Elmes
6491 volunteered to maintain EmacsWikiMode.
6495 John Wiegley wrote EmacsWikiMode and Planner.
6499 @cindex contributors
6501 For a complete list of people who have helped out with Planner, please
6502 check out the @file{AUTHORS} file that is included with Planner.
6506 @node GNU General Public License, Concept Index, Acknowledgements, Top
6507 @comment node-name, next, previous, up
6508 @appendix GNU GENERAL PUBLIC LICENSE
6509 @center Version 2, June 1991
6511 @cindex GNU General Public License
6513 @c This file is intended to be included in another file.
6516 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6517 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
6519 Everyone is permitted to copy and distribute verbatim copies
6520 of this license document, but changing it is not allowed.
6523 @appendixsec Preamble
6525 The licenses for most software are designed to take away your
6526 freedom to share and change it. By contrast, the GNU General Public
6527 License is intended to guarantee your freedom to share and change free
6528 software---to make sure the software is free for all its users. This
6529 General Public License applies to most of the Free Software
6530 Foundation's software and to any other program whose authors commit to
6531 using it. (Some other Free Software Foundation software is covered by
6532 the GNU Library General Public License instead.) You can apply it to
6535 When we speak of free software, we are referring to freedom, not
6536 price. Our General Public Licenses are designed to make sure that you
6537 have the freedom to distribute copies of free software (and charge for
6538 this service if you wish), that you receive source code or can get it
6539 if you want it, that you can change the software or use pieces of it
6540 in new free programs; and that you know you can do these things.
6542 To protect your rights, we need to make restrictions that forbid
6543 anyone to deny you these rights or to ask you to surrender the rights.
6544 These restrictions translate to certain responsibilities for you if you
6545 distribute copies of the software, or if you modify it.
6547 For example, if you distribute copies of such a program, whether
6548 gratis or for a fee, you must give the recipients all the rights that
6549 you have. You must make sure that they, too, receive or can get the
6550 source code. And you must show them these terms so they know their
6553 We protect your rights with two steps: (1) copyright the software, and
6554 (2) offer you this license which gives you legal permission to copy,
6555 distribute and/or modify the software.
6557 Also, for each author's protection and ours, we want to make certain
6558 that everyone understands that there is no warranty for this free
6559 software. If the software is modified by someone else and passed on, we
6560 want its recipients to know that what they have is not the original, so
6561 that any problems introduced by others will not reflect on the original
6562 authors' reputations.
6564 Finally, any free program is threatened constantly by software
6565 patents. We wish to avoid the danger that redistributors of a free
6566 program will individually obtain patent licenses, in effect making the
6567 program proprietary. To prevent this, we have made it clear that any
6568 patent must be licensed for everyone's free use or not licensed at all.
6570 The precise terms and conditions for copying, distribution and
6571 modification follow.
6574 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6577 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6582 This License applies to any program or other work which contains
6583 a notice placed by the copyright holder saying it may be distributed
6584 under the terms of this General Public License. The ``Program'', below,
6585 refers to any such program or work, and a ``work based on the Program''
6586 means either the Program or any derivative work under copyright law:
6587 that is to say, a work containing the Program or a portion of it,
6588 either verbatim or with modifications and/or translated into another
6589 language. (Hereinafter, translation is included without limitation in
6590 the term ``modification''.) Each licensee is addressed as ``you''.
6592 Activities other than copying, distribution and modification are not
6593 covered by this License; they are outside its scope. The act of
6594 running the Program is not restricted, and the output from the Program
6595 is covered only if its contents constitute a work based on the
6596 Program (independent of having been made by running the Program).
6597 Whether that is true depends on what the Program does.
6600 You may copy and distribute verbatim copies of the Program's
6601 source code as you receive it, in any medium, provided that you
6602 conspicuously and appropriately publish on each copy an appropriate
6603 copyright notice and disclaimer of warranty; keep intact all the
6604 notices that refer to this License and to the absence of any warranty;
6605 and give any other recipients of the Program a copy of this License
6606 along with the Program.
6608 You may charge a fee for the physical act of transferring a copy, and
6609 you may at your option offer warranty protection in exchange for a fee.
6612 You may modify your copy or copies of the Program or any portion
6613 of it, thus forming a work based on the Program, and copy and
6614 distribute such modifications or work under the terms of Section 1
6615 above, provided that you also meet all of these conditions:
6619 You must cause the modified files to carry prominent notices
6620 stating that you changed the files and the date of any change.
6623 You must cause any work that you distribute or publish, that in
6624 whole or in part contains or is derived from the Program or any
6625 part thereof, to be licensed as a whole at no charge to all third
6626 parties under the terms of this License.
6629 If the modified program normally reads commands interactively
6630 when run, you must cause it, when started running for such
6631 interactive use in the most ordinary way, to print or display an
6632 announcement including an appropriate copyright notice and a
6633 notice that there is no warranty (or else, saying that you provide
6634 a warranty) and that users may redistribute the program under
6635 these conditions, and telling the user how to view a copy of this
6636 License. (Exception: if the Program itself is interactive but
6637 does not normally print such an announcement, your work based on
6638 the Program is not required to print an announcement.)
6641 These requirements apply to the modified work as a whole. If
6642 identifiable sections of that work are not derived from the Program,
6643 and can be reasonably considered independent and separate works in
6644 themselves, then this License, and its terms, do not apply to those
6645 sections when you distribute them as separate works. But when you
6646 distribute the same sections as part of a whole which is a work based
6647 on the Program, the distribution of the whole must be on the terms of
6648 this License, whose permissions for other licensees extend to the
6649 entire whole, and thus to each and every part regardless of who wrote it.
6651 Thus, it is not the intent of this section to claim rights or contest
6652 your rights to work written entirely by you; rather, the intent is to
6653 exercise the right to control the distribution of derivative or
6654 collective works based on the Program.
6656 In addition, mere aggregation of another work not based on the Program
6657 with the Program (or with a work based on the Program) on a volume of
6658 a storage or distribution medium does not bring the other work under
6659 the scope of this License.
6662 You may copy and distribute the Program (or a work based on it,
6663 under Section 2) in object code or executable form under the terms of
6664 Sections 1 and 2 above provided that you also do one of the following:
6668 Accompany it with the complete corresponding machine-readable
6669 source code, which must be distributed under the terms of Sections
6670 1 and 2 above on a medium customarily used for software interchange; or,
6673 Accompany it with a written offer, valid for at least three
6674 years, to give any third party, for a charge no more than your
6675 cost of physically performing source distribution, a complete
6676 machine-readable copy of the corresponding source code, to be
6677 distributed under the terms of Sections 1 and 2 above on a medium
6678 customarily used for software interchange; or,
6681 Accompany it with the information you received as to the offer
6682 to distribute corresponding source code. (This alternative is
6683 allowed only for noncommercial distribution and only if you
6684 received the program in object code or executable form with such
6685 an offer, in accord with Subsection b above.)
6688 The source code for a work means the preferred form of the work for
6689 making modifications to it. For an executable work, complete source
6690 code means all the source code for all modules it contains, plus any
6691 associated interface definition files, plus the scripts used to
6692 control compilation and installation of the executable. However, as a
6693 special exception, the source code distributed need not include
6694 anything that is normally distributed (in either source or binary
6695 form) with the major components (compiler, kernel, and so on) of the
6696 operating system on which the executable runs, unless that component
6697 itself accompanies the executable.
6699 If distribution of executable or object code is made by offering
6700 access to copy from a designated place, then offering equivalent
6701 access to copy the source code from the same place counts as
6702 distribution of the source code, even though third parties are not
6703 compelled to copy the source along with the object code.
6706 You may not copy, modify, sublicense, or distribute the Program
6707 except as expressly provided under this License. Any attempt
6708 otherwise to copy, modify, sublicense or distribute the Program is
6709 void, and will automatically terminate your rights under this License.
6710 However, parties who have received copies, or rights, from you under
6711 this License will not have their licenses terminated so long as such
6712 parties remain in full compliance.
6715 You are not required to accept this License, since you have not
6716 signed it. However, nothing else grants you permission to modify or
6717 distribute the Program or its derivative works. These actions are
6718 prohibited by law if you do not accept this License. Therefore, by
6719 modifying or distributing the Program (or any work based on the
6720 Program), you indicate your acceptance of this License to do so, and
6721 all its terms and conditions for copying, distributing or modifying
6722 the Program or works based on it.
6725 Each time you redistribute the Program (or any work based on the
6726 Program), the recipient automatically receives a license from the
6727 original licensor to copy, distribute or modify the Program subject to
6728 these terms and conditions. You may not impose any further
6729 restrictions on the recipients' exercise of the rights granted herein.
6730 You are not responsible for enforcing compliance by third parties to
6734 If, as a consequence of a court judgment or allegation of patent
6735 infringement or for any other reason (not limited to patent issues),
6736 conditions are imposed on you (whether by court order, agreement or
6737 otherwise) that contradict the conditions of this License, they do not
6738 excuse you from the conditions of this License. If you cannot
6739 distribute so as to satisfy simultaneously your obligations under this
6740 License and any other pertinent obligations, then as a consequence you
6741 may not distribute the Program at all. For example, if a patent
6742 license would not permit royalty-free redistribution of the Program by
6743 all those who receive copies directly or indirectly through you, then
6744 the only way you could satisfy both it and this License would be to
6745 refrain entirely from distribution of the Program.
6747 If any portion of this section is held invalid or unenforceable under
6748 any particular circumstance, the balance of the section is intended to
6749 apply and the section as a whole is intended to apply in other
6752 It is not the purpose of this section to induce you to infringe any
6753 patents or other property right claims or to contest validity of any
6754 such claims; this section has the sole purpose of protecting the
6755 integrity of the free software distribution system, which is
6756 implemented by public license practices. Many people have made
6757 generous contributions to the wide range of software distributed
6758 through that system in reliance on consistent application of that
6759 system; it is up to the author/donor to decide if he or she is willing
6760 to distribute software through any other system and a licensee cannot
6763 This section is intended to make thoroughly clear what is believed to
6764 be a consequence of the rest of this License.
6767 If the distribution and/or use of the Program is restricted in
6768 certain countries either by patents or by copyrighted interfaces, the
6769 original copyright holder who places the Program under this License
6770 may add an explicit geographical distribution limitation excluding
6771 those countries, so that distribution is permitted only in or among
6772 countries not thus excluded. In such case, this License incorporates
6773 the limitation as if written in the body of this License.
6776 The Free Software Foundation may publish revised and/or new versions
6777 of the General Public License from time to time. Such new versions will
6778 be similar in spirit to the present version, but may differ in detail to
6779 address new problems or concerns.
6781 Each version is given a distinguishing version number. If the Program
6782 specifies a version number of this License which applies to it and ``any
6783 later version'', you have the option of following the terms and conditions
6784 either of that version or of any later version published by the Free
6785 Software Foundation. If the Program does not specify a version number of
6786 this License, you may choose any version ever published by the Free Software
6790 If you wish to incorporate parts of the Program into other free
6791 programs whose distribution conditions are different, write to the author
6792 to ask for permission. For software which is copyrighted by the Free
6793 Software Foundation, write to the Free Software Foundation; we sometimes
6794 make exceptions for this. Our decision will be guided by the two goals
6795 of preserving the free status of all derivatives of our free software and
6796 of promoting the sharing and reuse of software generally.
6799 @heading NO WARRANTY
6806 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6807 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6808 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6809 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6810 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6811 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6812 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6813 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6814 REPAIR OR CORRECTION.
6817 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6818 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6819 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6820 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6821 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6822 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6823 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6824 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6825 POSSIBILITY OF SUCH DAMAGES.
6829 @heading END OF TERMS AND CONDITIONS
6832 @center END OF TERMS AND CONDITIONS
6836 @appendixsec Appendix: How to Apply These Terms to Your New Programs
6838 If you develop a new program, and you want it to be of the greatest
6839 possible use to the public, the best way to achieve this is to make it
6840 free software which everyone can redistribute and change under these terms.
6842 To do so, attach the following notices to the program. It is safest
6843 to attach them to the start of each source file to most effectively
6844 convey the exclusion of warranty; and each file should have at least
6845 the ``copyright'' line and a pointer to where the full notice is found.
6848 @var{one line to give the program's name and a brief idea of what it does.}
6849 Copyright (C) @var{yyyy} @var{name of author}
6851 This program is free software; you can redistribute it and/or modify
6852 it under the terms of the GNU General Public License as published by
6853 the Free Software Foundation; either version 2 of the License, or
6854 (at your option) any later version.
6856 This program is distributed in the hope that it will be useful,
6857 but WITHOUT ANY WARRANTY; without even the implied warranty of
6858 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6859 GNU General Public License for more details.
6861 You should have received a copy of the GNU General Public License
6862 along with this program; if not, write to the Free Software
6863 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
6866 Also add information on how to contact you by electronic and paper mail.
6868 If the program is interactive, make it output a short notice like this
6869 when it starts in an interactive mode:
6872 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6873 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
6874 This is free software, and you are welcome to redistribute it
6875 under certain conditions; type `show c' for details.
6878 The hypothetical commands @samp{show w} and @samp{show c} should show
6879 the appropriate parts of the General Public License. Of course, the
6880 commands you use may be called something other than @samp{show w} and
6881 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6884 You should also get your employer (if you work as a programmer) or your
6885 school, if any, to sign a ``copyright disclaimer'' for the program, if
6886 necessary. Here is a sample; alter the names:
6889 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
6890 `Gnomovision' (which makes passes at compilers) written by James Hacker.
6892 @var{signature of Ty Coon}, 1 April 1989
6893 Ty Coon, President of Vice
6896 This General Public License does not permit incorporating your program into
6897 proprietary programs. If your program is a subroutine library, you may
6898 consider it more useful to permit linking proprietary applications with the
6899 library. If this is what you want to do, use the GNU Library General
6900 Public License instead of this License.
6902 @node Concept Index, , GNU General Public License, Top
6903 @comment node-name, next, previous, up