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://wjsullivan.net/static/doc/planner/}.
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://mwolson.org/static/doc/muse.html}.
315 Planner and Muse are intended to work with version 21 or later of Emacs
318 Make sure that you use the latest Muse release. Development code might
322 * Getting the Files::
323 * Creating Your Planner::
325 * Advanced Installation::
328 @node Getting the Files, Creating Your Planner, Installation, Installation
329 @comment node-name, next, previous, up
330 @section Getting the Files
332 Currently, there are three ways to obtain and install Planner. You can
333 install it from a source archive, Arch repository, or Debian package.
336 * Installing from a Source Archive::
337 * Installing from Arch::
338 * Installing from Debian::
341 @node Installing from a Source Archive, Installing from Arch, Getting the Files, Getting the Files
342 @comment node-name, next, previous, up
343 @subsection Installing from a Source Archive
344 @cindex source code archive, installing from
346 You can install Planner from the source archive packaged and
347 distributed directly by the maintainer. This archive is provided in
348 both @file{.tar.gz} and @file{.zip} format. If you don't know where to
349 extract these archives, create a @file{~/elisp} directory, and extract
354 Download and unpack either
355 @url{http://mwolson.org/static/dist/planner-latest.tar.gz} or
356 @url{http://mwolson.org/static/dist/planner-latest.zip}.
360 @url{http://mwolson.org/static/dist/muse-latest.tar.gz} or
361 @url{http://mwolson.org/static/dist/muse-latest.zip}.
365 @url{http://mwolson.org/static/dist/remember-latest.tar.gz} or
366 @url{http://mwolson.org/static/dist/remember-latest.zip}.
368 @item Edit your @file{~/.emacs} (@file{_emacs} on Microsoft Windows).
370 Replace @file{/path/to} with wherever you extracted the files.
373 ;; Add the directories to your load path
374 (add-to-list 'load-path "/path/to/muse/lisp")
375 (add-to-list 'load-path "/path/to/planner")
376 (add-to-list 'load-path "/path/to/remember")
383 @subheading Updating Your Version
385 Download a new version and extract it over the old directory. Don't
386 forget to delete any byte-compiled files (@file{*.elc}) in the
387 directories (which can be accomplished by running ``make clean'') so
388 that the new code will be used.
390 @node Installing from Arch, Installing from Debian, Installing from a Source Archive, Getting the Files
391 @comment node-name, next, previous, up
392 @subsection Installing from Arch
393 @cindex Arch repositories
394 @cindex Arch, installing from
396 Arch allows you to retrieve previous versions and select specific
397 features and bugfixes. Debian users can install Arch with @kbd{apt-get
398 install tla}. Users of other distributions should see
399 @url{http://regexps.srparish.net/www/}.
401 To get started with Planner using Arch, you'll need to run some initial
402 commands to register your local copy of the archive and retrieve the
406 # Register the Muse archive
407 tla register-archive -f http://mwolson.org/archives/2006
409 # Register the Planner archive
410 tla register-archive -f http://arch.gna.org/planner-el/archive-2006
412 # Register the Remember archive
413 tla register-archive -f http://arch.gna.org/remember-el/archive
416 tla get mwolson@@gnu.org--2006/muse--main--1.0 muse
418 # Download planner module into the planner/ subdirectory
419 tla get mwolson@@gnu.org--2006-planner-el/planner-el--devel--0 planner
422 tla get remember-el@@arch.gna.org/remember--main--0 remember
426 Then add the following lines to your @code{~/.emacs}:
429 ;; Add the directories to your load path
430 (add-to-list 'load-path "/path/to/muse/lisp")
431 (add-to-list 'load-path "/path/to/planner")
432 (add-to-list 'load-path "/path/to/remember")
438 You can also browse Planner's Arch repository on the web at
439 @url{http://archzoom.mwolson.org/cgi-bin/archzoom.cgi/mwolson@@gnu.org--2006-planner-el}.
441 @subheading Updating Your Version
442 @cindex Arch, updating from
444 To stay up-to-date using Arch, here are some commands that might be
447 To list upstream changes not in local copy:
450 # Change to the source directory you are interested in. Example:
453 # Display the summary of changes
454 tla missing --summary
457 To update to the latest version:
461 cd ../planner; tla update
462 cd ../remember; tla update
465 Don't forget to delete any byte-compiled files (@file{*.elc}) in the
466 directories so that the new code will be used.
468 @node Installing from Debian, , Installing from Arch, Getting the Files
469 @comment node-name, next, previous, up
470 @subsection Installing from Debian
471 @cindex Debian package
473 Debian packages for Planner, Muse, and Remember are available in Debian
474 proper as the @code{planner-el}, @code{muse-el}, and @code{remember-el}
475 packages, respectively.
477 If you wish to try experimental packages, add the following lines to
478 your @file{/etc/apt/sources.list}
481 deb http://mwolson.org/debian/ ./
484 Then, do the following steps as root:
488 apt-get install muse-el
489 apt-get install planner-el
490 apt-get install remember-el
493 If you get some warning about the key not being trusted, you can either
494 ignore it or do the following.
497 gpg --keyserver pgpkeys.mit.edu --recv-key f3a8d319
498 gpg -a --export f3a8d319 | sudo apt-key add -
501 @subheading Updating Your Version
502 @cindex Debian package, updating
504 If you installed Planner from Debian, do @kbd{apt-get update; apt-get
505 upgrade} to upgrade all packages that can be upgraded, or @kbd{apt-get
506 update; apt-get install planner-el} to upgrade just planner-el.
508 @node Creating Your Planner, Components, Getting the Files, Installation
509 @section Creating Your Planner
511 Now that you have installed the files for Planner and Muse, you need
512 to set some options to create your first planner.
514 Muse thinks in terms of projects. Each project consists of a group of
515 documents and certain information associated with these
516 documents. Planner is organized as a project within Muse. So, you need
517 to tell Muse a bit about it.
519 Add something like the following code to your @file{.emacs} file.
521 First, give your new Planner project a name. In this case, we use the
522 name, ``WikiPlanner''.
525 (setq planner-project "WikiPlanner")
528 Next, add an entry for your project to Muse's master list of
529 projects. Don't forget to use your own name here in place of
530 ``WikiPlanner'' if you have chosen something different.
533 (setq muse-project-alist
535 ("~/Plans" ;; where your Planner pages are located
536 :default "TaskPool" ;; use value of `planner-default-page'
537 :major-mode planner-mode
538 :visit-link planner-visit-link)
540 ;; This next part is for specifying where Planner pages
541 ;; should be published and what Muse publishing style to
542 ;; use. In this example, we will use the XHTML publishing
545 (:base "planner-xhtml"
546 ;; where files are published to
547 ;; (the value of `planner-publishing-directory', if
548 ;; you have a configuration for an older version
550 :path "~/public_html/Plans"))))
553 This code should work fine as-is for you as long as the directories
554 you see exist, and as long as you have no other Muse projects besides
557 The first directory (@file{~/Plans}) is the directory where the
558 source files for your planner will reside. This is the directory where
559 you will actually visit files and edit them. These files must have a
562 The second directory (@file{~/public_html/Plans}) is the directory
563 where your planner files will be published by Muse as XHTML
564 (@pxref{Publishing}).
566 After you have added this code, make sure to either evaluate it or
569 @node Components, Advanced Installation, Creating Your Planner, Installation
570 @comment node-name, next, previous, up
573 Now that you have the archive, let's look at what's in it.
575 There should be three directories, named @file{planner}, @file{muse} and
578 In the @file{planner/} directory, you'll see many files with names like
579 @file{planner-gnus.el}. These are extra modules and extensions for
580 Planner, which you can use to tailor Planner to fit your desired
581 planning and information management habits.
583 In the @file{muse/lisp} directory, you'll see many files with names like
584 @file{muse-blosxom.el}. As in @file{planner/}, these are optional
585 modules and extensions.
587 A minimal working installation includes just @file{planner/planner.el}.
589 You need @file{planner.el} because it provides the core functions for
590 handling tasks, notes, and page navigation. You need @file{Emacs Muse}
591 because it provides the functions used to display your pages (both in an
592 emacs buffer and as HTML), and for connecting them to each other. More
593 specifically, it enables you to have hyperlinks and formatting in your
594 emacs buffers even though the actual files you are working with are
595 saved in plain text. These abilities are used in Planner to format your
596 planner pages the way you like, to create links from your tasks and
597 notes to the materials and projects they refer to, and to optionally
598 ``publish'' your pages in different formats, including HTML.
600 In the @file{remember/} directory are files related to
601 RememberMode. RememberMode does not depend on Planner or Muse, but works
602 best with Planner installed. It is not required in order to use Planner,
603 but it is used by many Planner users to record notes and information to
606 If you are curious, you can open each file in these directories and read
607 the comments at the top, to get an idea of what each extension is used
608 for. They are also all detailed later in this manual.
610 @node Advanced Installation, , Components, Installation
611 @comment node-name, next, previous, up
612 @section Advanced Installation
614 Once you decide you want to keep Planner around for a while, there
615 are two additional steps you can take to make using it easier and more
616 efficient. These steps are optional.
619 @cindex installing the info file
620 @cindex @file{planner-el.texi}, installing
621 @cindex @file{planner-el.info}, installing
622 @item You can make this document, the Planner info file, appear in
623 the index of info files you see when you type @command{M-x info} or
624 @kbd{C-h i} in Emacs. The instructions for doing this vary depending
625 on whether you have permission to edit certain files on your
626 system. Follow the instructions in @ref{Installing an Info File, ,
627 ,texinfo, Texinfo}, using something like:
630 * Planner: (path/to/planner/Planner). Organizer/day planner
634 for the new entry in the info @file{dir} file.
636 @cindex byte compiling
637 @item You can byte-compile @file{planner.el}, @file{Muse},
638 @file{remember.el}, or any of the optional modules you frequently use,
639 in order to improve the speed of their execution. Basically, all you
640 need to do is change to the directory of each project in
641 @file{scripts/planner-build.el} and run @command{make} from the command
642 line. To read more detail about byte compilation, see
643 @ref{Byte Compilation, , ,elisp, Emacs Lisp Reference Manual}.
647 @node Overview, Getting Started, Installation, Top
648 @comment node-name, next, previous, up
651 Planner is a plain-text hyperlinked personal information manager
652 for Emacs that helps you keep track of tasks, notes, and other
653 information. People use Planner to support different ways of planning
654 one's day, from Franklin-Covey and David Allen's Getting Things Done
655 to home-brew hacks. Planner is even used to manage information not
656 normally handled by a personal information manager, like bugtracking,
657 time tracking, and team data. If you start by using Planner as a basic
658 TODO and notes manager, you might find other ways it can help you
659 improve your process.
661 You can use Planner to keep track of your tasks, schedule, notes,
662 and other information you want to store in hyperlinkable text files.
663 You can get the most benefit out of a personal information manager if
664 you use it everyday. Most people add @code{(plan)} to the end of their
665 @file{~/.emacs} so that Planner shows today's schedule and
666 unfinished tasks whenever Emacs starts. If you leave your Emacs
667 running for more than 24 hours, try to get into the habit of running
668 @code{plan} at least once a day.
670 Because your time is important, Planner tries to minimize
671 distractions, making it easier for you to jot down tasks and notes
672 without being distracted from your work. People often make tasks based
673 on the current buffer, so Planner tries to create hyperlinks to
674 whatever you're looking at so that you can jump back to it easily. The
675 @ref{Getting Started} tutorial will show you how to set that up for
676 both tasks and notes.
678 The customizability of Planner means you can make your personal
679 information manager truly personal. Planner strives to be as flexible
680 as possible, and we would love to adapt Planner to fit your needs.
681 Browse through our mailing list (@pxref{Getting Help}) to
682 find out how other people are using Planner, and post your feature
683 requests and bug reports there!
685 Planner is just a tool. It does not dictate a particular way of
686 planning, although it supports some ways better than it supports
687 others. If you want to take some time thinking about planning, read
688 the following reflections for inspiration and ideas. On the other
689 hand, if you want to hit the ground running, see @ref{Getting
690 Started}. If you already have a specific way of planning in mind,
691 check out @ref{Sample Configuration Files}.
694 * Planning based on the Franklin-Covey Approach::
698 @node Planning based on the Franklin-Covey Approach, Why Use Planner, Overview, Overview
699 @comment node-name, next, previous, up
700 @section Planning Based on the Franklin-Covey Approach
701 @cindex philosophy of planning
703 (This is an edited and updated version of an essay originally by John
704 Wiegley. Read it if you want to get some insights into one way of
705 planning. You can skip this if you want to go straight to planning your
708 What is planning? It can be a nebulous thing to define. In its
709 essence, however, it is very simple: it's how we achieve our dreams.
711 Our days are filled with time, and hence with actions, whether they
712 be of a mental or physical sort. But there are two kinds of
713 action: reactive and creative. Reactive action is a response to
714 the environment, a reaction to stimulus. Had we enough instincts
715 to ensure survival, we could live according to this kind of action
716 alone. It is a mode of behavior we share with every living
719 The opposite to reactivity is creativity, when we decide upon a
720 course of action that is a wholly a product of personal choice. We
721 then make decisions as to the steps needed to make this wish a
722 reality. This is planning. Planning is essentially a creative
723 endeavor at every step.
725 First, create the idea, what you want to achieve. Very short-term
726 ideas do not need much more than thinking about how to do it. But
727 long-term ideas require planning, since the mind cannot contain all
730 Second, decide how the idea maps into the circumstances you find
731 yourself in. Some environments will assist your plan, others
732 hinder it. But step by step, identify every barrier to the
733 realization of your idea, and devise a countermeasure to overcome
734 it. Once you've mapped things out from beginning to end,
735 accounting for unknowables as best you can, you now have your plan.
737 Third is to break the stages of the plan into parts that are not
738 overwhelming in their complexity. It is at during this phase that
739 a plan is turned into task items, each to be accomplished within
740 the span of one day's time. If a task requires several days, break
741 it up further. The smaller it is, the less your mind will recoil
744 Fourth is to monitor your progress, identifying problems and
745 correcting for them as you go. Some plans start out unachievable,
746 and remain that way indefinitely, due to a simple lack of
747 observation. If nothing is working for you, change it. Otherwise,
748 your plan is merely a well-crafted wish.
750 Fifth is just to do the work, and be patient. All good plans take a
751 great deal of time, and *cannot* happen immediately. The groundwork
752 must be laid for each step, or else it will rest on an insecure
753 foundation. If you follow your plan doggedly, applying some time to
754 it each day or week, it @emph{will} happen. Remember the story of the
755 tortoise and the hare. I've even written a short essay on the
756 necessity of gradual accomplishment, which can be found at
757 @url{http://emacswiki.org/johnw/essays/node2.html}.
759 How can this software help? Computers are ideal for manipulating
760 information, since they allow you to change things without erasing
761 or rewriting. And since all plans change quite a bit during their
762 implementation, a planning program can be very helpful.
764 Start by installing Planner and Muse (@pxref{Installation}).
766 Now, conceive your idea. I can't believe there's nothing you want
767 from life. More peace, time to enjoy the world, an end to war?
768 Everyone wants something. Search deeply, and you will find
769 countless unhoped wishes lurking therein. Choose one for now, and
770 think on it for a while.
772 Then open a file (using @kbd{C-x C-f}) within the directory you named in
773 your @code{muse-project-alist}. Make sure the file has a @file{.muse}
774 extension so that Emacs will automatically recognize it as a planner
775 file. Name the file after your plan, such as @file{BetterHealth.muse}.
777 Choose an idea you really want to accomplish. Struggle to
778 differentiate between the things you want because others want them,
779 and the things you want for yourself. It takes quite an effort, and
780 may require a long time before you notice the difference. Many people
781 want to be more healthy to be more attractive, which is an externally
782 driven goal. Unless @emph{you} really want to accomplish what you
783 envision, the odds are you will fail. Only our own wishes and dreams
784 possess enough personal energy to see themselves to fruition. What
785 happens to many of us is simply that we never become conscious of
786 these dreams: what we love, what we desire most. When I talk to
787 friends, so much of what I hear is things they want because they feel
788 they should want them. There's just not enough energy there to pursue
789 a good plan, because nearly all of it is negative energy.
791 Do you know what you really want? Don't worry, many people don't.
792 It's not a question anyone really wants us to pursue, because often
793 we don't want what others do; it doesn't contribute to the social
794 welfare, and all that nonsense. Somehow we always forget that
795 what's good for the social welfare now, was someone else's crazy
796 dream a hundred years ago. The human aversion to fundamental
797 change is always one's greatest enemy, so don't waste any time
798 getting bitter about it.
800 For the sake of argument I assume you really do want to be
801 healthier, because you've fallen in love with the ideal of purity,
802 or you understand the connection between your physical self and the
803 world around you, and how this can open up your spirit to desiring
806 So you're in a Wiki file called @file{BetterHealth}. Start typing.
807 Type anything related to your idea: what you think about it, your
808 ideas on it, @emph{and especially what the end will look like}. If
809 you can't visualize the end, you can't plan, since planning is about
810 drawing a line between now and then.
812 When you've typed enough to gain a vision of your goal, start
813 drafting what the possible intermediate steps might be. Then stop,
814 get up, walk around, enjoy life, and come back to it. Taking a
815 long time at the beginning is not a bad idea at all, as long as
818 As you chew on your idea, it will begin to become more and more
819 concrete. You'll have ideas about the smallest pieces, and ideas
820 about the biggest pieces. Keep going until it starts to take shape
821 before you, and you can see yourself in your mind's eye moving from
822 the present into the future. Write down this progression, and the
823 sorts of things you might encounter along the way.
825 As you continue, you'll naturally discover discrete phases, or
826 ``milestones'' as managers love to call them. These are very
827 important, because they let you know you're making progress. I
828 recommend having a big party with friends every time you achieve a
829 milestone. A typical plan might have between three and ten.
831 Between the milestones are the bigger pieces of your plan. You might
832 find it convenient to name these pieces using MixedCase words. Try
833 adding these lines to your @file{.emacs} or @file{_emacs} file.
837 (setq muse-wiki-allow-nonexistent-wikiword t)
840 You'll notice that Emacs colors and underlines them for you. Like,
841 FindGoodGym. Hit return on this highlighted word, and you'll find
842 yourself in another, blank file. In this file, start drafting your
843 sub-plan, just as you did with the larger plan. You should find it
844 easier now, since the scope is smaller.
846 As you break down further, you'll notice simple little things that
847 need to get done. These are your tasks. Every plan is a
848 succession of tasks. The difference from reactivity is that each
849 task is part of the larger plan. This is what it means to be
850 systematic: that everything you do helps further your plan. If you
851 have tasks in your day that contribute to no plan, they are
852 reactive. Of course, life is full of these, but don't let them
853 take up more than 20% of your day. If you allow yourself to be
854 dominated by reactive tasks, you'll regret it at the end of your
855 life. I don't know this personally, but I do know that striving
856 for one's dreams -- and seeing them come to fruition -- is the
857 greatest joy a man can possess. It is the essence of freedom, of
858 living, of creation. Reactivity is the opposite of this, and
859 serves only to drain our energy and slacken our spirits.
861 Now that you've thought of a simple task, type @kbd{C-c C-t}. This
862 will ask for a brief description of the task, and when you plan to do
863 it. If you hit @key{RETURN} at the question @samp{When}, it assumes
864 you mean today. It will also pop up a three-month calendar at this
865 question, so you can see where your free days are. Make sure you set
866 the variable @code{mark-diary-entries-in-calendar} to @samp{t} in your
867 @file{.emacs} (or @file{_emacs}) file. This way, you can see which
868 days your appointments fall on. (Read about the Emacs Calendar and
869 Diary in @ref{Calendar/Diary, , , Emacs, GNU Emacs Manual}.)
872 (setq mark-diary-entries-in-calendar t)
875 Once your task is in there, go back to your plan and keep
876 generating more tasks. Generate them all! Fully describe---as
877 tasks---everything necessary to bring your sub-plan to completion.
878 Don't create tasks for the other sub-plans. You may have good idea
879 of what they'll look like, but don't bother rendering them into
880 tasks just yet. Things will change too much between now and then,
881 for that to be a good use of your time.
883 Is your sub-plan now rendered into all of the tasks necessary to
884 reach your first milestone? Great! That is the purpose of
885 planner.el. The rest is really up to you. If you find that you
886 keep putting things off, and never do them, that's the surest sign
887 you're planning for someone else's dream, and not your own.
889 Here are some of the things planner.el can do, to help you manage
890 and track your tasks:
892 At the beginning of every day, type @kbd{M-x plan}. This will jump
893 you to the top of the most recent task list before today. If you
894 skipped a bunch of days, you'll have to open up those files on your
897 Probably some of the tasks that day won't be finished -- that's OK.
898 Learning to properly estimate time is a magical, mystical art that few
899 have mastered. Put your cursor on those undone tasks, and type
900 @kbd{C-c C-c}. This will move them into today's task page. You can
901 jump to today's task page at any time by typing @kbd{C-c C-n} (from a
902 Wiki or planning page). I heartily recommend binding @kbd{C-c n}, to
903 jump you to this page from anywhere:
906 (define-key mode-specific-map [?n] 'planner-goto-today)
909 As you look at your task sheet each day, the first thing to do is to
910 ``clock in'' to one of them. This isn't necessary, and is only helpful
911 if you're around your computer a lot. But by typing @kbd{C-c C-i}
912 (assuming you have @file{timeclock.el} on your load-path), it will log
913 the time you spend working on your sub-plan (@pxref{Time Intervals, , ,
914 Emacs, GNU Emacs Manual}). This is helpful for viewing your progress.
915 Type @kbd{C-c C-o} to clock out.
917 @kbd{C-M-p} and @kbd{C-M-n} will move a task up and down in priority.
918 Priority is represented by a letter A through C. 'A' tasks mean they
919 must be done that day, or else your plan is compromised and you will
920 have to replan. 'B' means they should be done that day, to further the
921 plan, otherwise things will be delayed. 'C' means you can put off the
922 task if you need to, although ultimately it will have to be done.
924 For reactive tasks, the letters mean something different: 'A' means
925 you must do it today, or somebody will roast your chestnuts over an
926 open fire. 'B' means you should do it today, or else someone will
927 be practicing patience at the day's end. 'C' means no one will
928 notice if you don't do it.
930 Again, reactive tasks are ENEMIES OF PLANNING. Really, until you
931 see them that way, circumstances will push you around and steal
932 your life away. We have only so many years to use, and everyone is
933 greedy to take them. It's insidious, almost invisible. A healthy
934 dislike of reactivity will do wonders for organizing your affairs
935 according to their true priority.
937 The last word that needs to be said concerns ``roles''. Every person
938 stands in several positions in his life: husband, employee, manager,
939 etc. These roles will tend to generate tasks not associated with any
940 immediate plan, but necessary to maintain the health and functioning
941 of the role. My suggestion is to keep this the smallest possible
942 number, and fulfill those that remain well. How you decide to
943 apportion your time between pursuing grand designs, and fostering deep
944 relationships, is a personal matter. If you choose well, each will
947 I mention this to point that reactivity is something not
948 exclusively associated with tasks that have no master plan, because
949 being a father, for example, is something that rarely proceeds
950 according to orderly plans. But the role of father itself is its
951 own plan, whose goal is ``to be the best one can'', and whose
952 component tasks are spending time on whatever comes up. It is, in
953 a sense, an implicit plan. But reactive tasks follow no plan at
954 all; they are parasites of time that suck the spirit away, whereas
955 properly chose roles actually help fulfill one's own inner needs.
956 At least, this is what I believe.
958 @defun plan force-days
959 Start your planning for the day, beginning with the last day's tasks.
961 If @code{planner-carry-tasks-forward} is non-nil, find the most recent
962 daily page with unfinished tasks and reschedule those tasks to
963 the current day. If @var{force} is non-nil, examine all past daily
964 pages for unfinished tasks.
966 If @code{planner-carry-tasks-forward} is nil, visit the most recent
967 daily page. If a daily page for today exists, visit that instead.
969 If @var{force-days} is a positive integer, scan that number of days.
970 If @var{force-days} is @samp{t}, scan all days.
974 @node Why Use Planner, , Planning based on the Franklin-Covey Approach, Overview
975 @comment node-name, next, previous, up
976 @section Why Use Planner?
977 @cindex Planner, why use
979 You can skip this essay if you just want to get started, or read it
980 for some insights into why the previous maintainer is crazy about it.
982 Why I Use Planner, by Sacha Chua
984 I thought about why I liked Planner. Planner as a TODO manager
985 isn't particularly special. Although I can assign tasks to categories
986 and see a breakdown of what projects are taking up my time, Evolution
987 and Microsoft Outlook provide more powerful task support. In other
988 task managers, you can e-mail tasks, assign multiple categories and
989 fill in all sorts of metadata. You can even synchronize your tasks
990 with devices like a phone or PDA. So why use Planner?
992 I realized that integration into my way of life and automatic context
993 clues are what really make planner tasks worth it for me. I don't have
994 to switch to another application to create a task. I can just hit a
995 keyboard shortcut. Planner uses a minibuffer to get the task
996 description. My windows are not rearranged in any way, and I can look
997 at the data that's relevant to a task. Not only that, tasks
998 automatically pick up context clues, like whom I'm talking to on IRC
999 or the file I'm editing at the moment. This cuts down on the explicit
1000 context I need to include and makes it easier for me to bring up the
1003 As a scheduler, Planner is also not particularly distinguished.
1004 Sure, it can display my @file{~/diary}, but for that matter so can
1005 @kbd{M-x diary}. Evolution and Outlook can give me a more graphical
1006 view of my time, sync with my PDA, and coordinate my schedule with
1007 other people. Those applications support detailed schedule entries
1008 with powerful cyclic options. On the other hand, Planner gives me
1009 a personal, plain text view and (at least the way I use it) requires
1010 me to edit a separate file to add new appointments. (I've defined a
1011 few shortcut keys to deal with this.) However, it does have one
1012 advantage---my schedule is always loaded. I used to use Outlook on
1013 Windows, but having my schedule in a separate application meant that I
1014 actually looked at it very rarely, as I had turned off reminders
1015 because they got annoying.
1017 Planner's notes, however, are what really convinced me. I can hit
1018 a keyboard shortcut from anywhere and type my notes into a buffer
1019 which automatically keeps context information. After typing the note,
1020 I can then categorize it. I think that the critical thing here is that
1021 interruptions---fleeting thoughts---don't break my flow. I can just
1022 pop up a remember buffer, stow that thought away somewhere, and go
1023 back to it whenever I want. In contrast, creating a note in Outlook
1024 means switching out of my application, making a couple of keystrokes,
1025 typing the note in, and then switching back. The context switches make
1026 it hard to keep track of where I am and what I'm supposed to remember.
1027 Not only that, I need to enter context by hand. Even though I can
1028 color my notes and reorganize them in Outlook, I find the context
1029 switch too expensive. I used to keep notes in other knowledge
1030 management tools as well. Some applications allowed me to
1031 drag-and-drop links into the current note, and that was cool. But that
1032 required a manual action, and those applications didn't feel
1033 integrated into my way of working. (Note: You'll need remember.el for
1036 I guess that's why I like Planner. Unlike other organizers which
1037 don't know anything about the applications I use, Planner tries
1038 its best to integrate into the way I work, and it's easy to extend.
1039 Fortunately I do almost all my work in Emacs, so I can think of my
1040 organizer as integrated into my e-mail client, Internet Relay Chat
1041 client, web browser, file editor and even games. It automatically
1042 picks up context clues from these applications and allows me to easily
1043 jump back to relevant files. It doesn't distract me. It allows me to
1044 key in data and then it gets out of my way.
1046 (That said, it's perfectly okay to use Planner even if you don't live
1049 The processing that happens in the background is a bonus, and
1050 publishing my task list and notes online has greatly helped me. It
1051 gives other people a way to see what I'm working on and what I've
1052 planned for the future. Occasionally people write in with additional
1053 resources and helpful tips. (Again, this is purely optional. Many
1054 people don't publish their planner pages. Other people use really
1055 fine-grained access control.)
1057 I think the greatest feature of Planner, though, is its user
1058 community. Because Planner can be easily modified, we can experiment
1059 with a lot of new ideas quickly, and we can tailor Planner to fit our
1060 needs. I love checking my @samp{planner-el-discuss} mail and finding
1061 out how people have tweaked Planner or would like to tweak Planner,
1062 and I've learned a lot by exchanging reflections on organizing one's
1065 I really wasn't an organization freak before I started using Planner.
1066 I often forgot to do my homework or answer important mail. I still
1067 procrastinate now, but at least it's all being kept track of
1068 somewhere! I also really like how Planner lets me to gradually improve
1069 how I'm doing things, and I feel I've come a long way.
1071 Please try it out! We'd love to hear how Planner can become
1072 @emph{your} personal information manager.
1074 @node Getting Started, More about Planner, Overview, Top
1075 @comment node-name, next, previous, up
1076 @chapter Getting Started
1078 At the end of this tutorial, you will be able to use Planner and
1079 related modules to keep track of your tasks, schedules and notes, all
1080 within the convenience of Emacs.
1082 There are two kinds of pages in a Planner wiki. Day pages show tasks,
1083 schedule, and notes for the day, while plan pages organize related tasks
1084 and notes into a single page.
1086 If you have not yet added planner to your @file{~/.emacs}, add the
1090 (add-to-list 'load-path "/path/to/muse/lisp")
1091 (add-to-list 'load-path "/path/to/planner")
1092 (add-to-list 'load-path "/path/to/remember")
1096 This will bring up the most recent day page with unfinished tasks or
1097 create a new day page if necessary. By default, planner pages are
1098 stored in @samp{~/Plans} (@code{planner-directory}).
1109 @node Tasks, Schedule, Getting Started, Getting Started
1112 Let us start by creating a task labelled
1115 Join http://mail.gna.org/listinfo/planner-el-discuss/
1118 From anywhere (even this info buffer!), call @kbd{M-x
1119 planner-create-task-from-buffer} to create a new task. Fill in the
1120 description and choose a date by:
1123 @item typing 1 - 31 to put the task on that day of the month,
1124 @item accepting the default (today) by pressing RET,
1125 @item selecting the date with mouse-1,
1127 typing +n (where in is an integer) to schedule the task in n days time,
1129 @item typing nil to make an undated task.
1132 For now, accept the default (@samp{today}) by pressing @key{RET}.
1134 You will then be prompted for a plan page. Plan pages gather related
1135 tasks and notes, giving you an overview of what you've done so far.
1136 You can accept the default TaskPool, create your own plan page, or
1137 specify nil to make a task that is not associated with a plan page.
1138 For now, accept the default (@samp{TaskPool}) by pressing RET.
1140 You have created your first task. View today's page with
1141 @kbd{M-x planner-goto-today}. You will see a line of the form
1144 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
1147 If you created the task from this page, then there will be an additional
1151 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ : Tasks (TaskPool)
1154 The URL, @samp{TaskPool} and @samp{Getting Started} are
1155 hyperlinks. You can use TAB and S-TAB to navigate between them and RET
1158 Create more tasks using @kbd{M-x planner-create-task-from-buffer}.
1159 This is bound to @kbd{C-c C-t} in @code{planner-mode} pages
1160 for your convenience. For example, create the following tasks:
1164 @samp{Describe my current way of working and how I would like to work},
1165 for three days from now (@samp{+3}),
1167 @samp{Learn how to schedule a task}, an undated task (@kbd{nil}) on the
1170 @samp{Browse through the Planner info manual} for today (@kbd{.} or
1171 accept the defaults), and
1173 @samp{Add (plan) to the end of my [[~/.emacs]]} for today, but without a
1174 plan page (specify @kbd{nil} at the plan page prompt)
1177 Tip: I bind planner-create-task-from-buffer to "F9 t" so that I can
1178 easily call it from anywhere. You can do that with this elisp fragment:
1179 @code{(global-set-key (kbd "<f9> t") 'planner-create-task-from-buffer)}
1181 Next, visit the TaskPool by:
1185 @key{TAB}-bing or using the cursor and typing @key{RET} to follow the
1187 @item @kbd{C-x C-f TaskPool RET} to use @code{find-file}, or
1188 @item @kbd{C-c C-f TaskPool RET} to use @code{muse-project-find-file}
1191 You can see an overview of the tasks as scheduled on different days.
1192 Unlike many personal information managers that store all of your data
1193 in one file and then perform magic in order to present different
1194 views, Planner uses plain text files. The data is duplicated and kept
1195 updated by functions. This makes it simpler and easier to modify,
1196 because what you see is (almost) what you get. On the other hand,
1197 you'll need to get used to either editing both files, or using the
1198 built-in functions for editing and updating files. If you prefer not
1199 to work with linked tasks, you can configure Planner to use only plan
1200 pages or use only day pages.
1202 The TaskPool page should list the tasks you created earlier. Go to the
1203 one named Learn how to schedule a task . Type @kbd{C-c C-c}
1204 (@code{planner-copy-or-move-task}) to schedule the task. Type RET to
1205 accept the default (today). Go to the day page by following the link
1206 or calling @kbd{M-x planner-goto} (@kbd{C-c C-j C-d} or the menu bar);
1207 you will see the newly-created task there. You can also use @kbd{C-c
1208 C-c} (@kbd{planner-copy-or-move-task}) to reschedule a task to an
1209 earlier or later date.
1211 Well, that task is done. To mark the task as completed, type @kbd{C-c
1212 C-x} (@code{planner-task-done}). You can also edit the status manually
1213 (change _ to X) as long as you remember to call @kbd{M-x
1214 planner-update-task} to update the link page as well. Updating relies on
1215 the task description being the same, so do not edit this manually.
1217 Quick summary of commands:
1221 Go to today's page: @kbd{M-x plan} to carry unfinished tasks forward, or
1222 @kbd{M-x planner-goto-today} to just go to today's page.
1224 Create a task: @kbd{C-c C-t} (@code{planner-create-task-from-buffer}),
1225 or type a task manually (call M-x planner-update-task if the task is
1228 Mark a task as done: @kbd{C-c C-x} (@code{planner-task-done}), or edit
1229 the task and call @kbd{M-x planner-update-task}
1230 @item Edit a task description: @kbd{M-x planner-edit-task-description}
1231 @item Reschedule a task: @kbd{C-c C-c} (@code{planner-copy-or-move-task})
1233 Reschedule many tasks: Mark a region and use @kbd{M-x
1234 planner-copy-or-move-region}
1236 Change the plan of a task: @kbd{M-x planner-replan-task}, or do
1237 @kbd{C-c C-c} (@code{planner-copy-or-move-task}) and type in a
1238 plan page rather than a date
1239 @item Delete a task: @kbd{M-x planner-delete-task}
1241 Reorder tasks: @key{M-p} (@code{planner-raise-task}) and @key{M-n}
1242 (@code{planner-lower-task}), or normal editing commands like kill and
1244 @item Change task priorities (@samp{#A} > @samp{#B} > @samp{#C}):
1245 @key{C-M-p} (@code{planner-raise-task-priority}) and
1246 @key{C-M-n} (@code{planner-lower-task-priority}),
1247 or edit the task and call @kbd{M-x planner-update-task}.
1250 You can save your tasks with @kbd{C-x C-s} the same way you save any
1251 other file, or Emacs will prompt you to save it when you exit.
1253 @node Schedule, Notes, Tasks, Getting Started
1254 @comment node-name, next, previous, up
1257 This is free-form. You can put anything you want into this, or remove
1258 it from @code{planner-day-page-template} entirely. Some people use it
1259 to keep track of their plans for the day with tables like this:
1262 hh:mm | hh:mm | activity
1263 hh:mm | hh:mm | activity
1264 hh:mm | hh:mm | activity
1267 Remember, Planner files are just plain text. You can add new sections
1268 or remove old ones, or use the suggested sections for entirely
1269 different activities.
1271 @node Notes, Hyperlinks, Schedule, Getting Started
1272 @comment node-name, next, previous, up
1274 @cindex @file{remember.el}
1275 @cindex @file{remember-planner.el}
1278 By default, your Planner pages will have a Notes section. You can put
1279 anything you want in this section, or remove it from your
1280 @code{planner-day-page-template} entirely.
1282 You may be interested in @file{remember-planner.el}, part of the
1283 Remember package (see @inforef{Top, remember-el, remember-el}). You
1284 can download Remember at @uref{http://gna.org/projects/remember-el/}).
1286 @code{remember-planner.el} makes it easy to create notes from anywhere
1287 in Emacs, and it uses the same context-sensing code that Planner uses.
1288 Notes added by @code{remember-planner.el} look like this:
1294 [[context hyperlink]]
1297 and are outlined at the H2 level in published HTML.
1299 You can easily create context-aware notes if you include the following
1300 in your @file{~/.emacs}:
1303 (require 'remember-planner)
1304 (setq remember-handler-functions '(remember-planner-append))
1305 (setq remember-annotation-functions planner-annotation-functions)
1308 Then @kbd{M-x remember} will open a dedicated buffer for you to write
1309 your note. If Planner recognizes your current buffer as one with
1310 context then it will include a hyperlink at the bottom of the note.
1311 The first line of the note is used as a title, so make it short and
1312 meaningful. The rest of the text will be used as the body. Try it now
1313 by creating a note, perhaps about things you'd like to remember from
1316 Typing @kbd{C-c C-c} after composing will prompt for a plan page to
1317 put the note on, with auto-completion. If you don't enter a page, the
1318 note will just be saved on today's page. If you do specify a plan
1319 page, the note will go on both today's page and on the specified page.
1320 Let's try specifying @samp{TaskPool} for the note.
1322 If you look at today's page, you'll find a timestamped note that links
1323 to @samp{TaskPool}. Likewise, @samp{TaskPool} contains a note that
1324 links to today's page. To change the plan page of a note, use
1325 @kbd{planner-replan-note}.
1327 If you decide to edit the note on one of these pages after it has been
1328 saved, be aware that your changes will not be automatically reflected
1329 on the linked page. To update the linked page after editing a note,
1330 use @kbd{M-x planner-update-note}.
1332 @node Hyperlinks, Example Page, Notes, Getting Started
1336 Planner automatically creates context-sensitive hyperlinks for your
1337 tasks and notes when you use @code{planner-create-task-from-buffer}
1338 and @code{remember}.
1340 Blue links indicate URLs and Planner pages that already exist. Red links
1341 indicate Planner pages that have not yet been created.
1343 Middle-click or type @key{RET} on any link to view the link in the
1344 current window. Shift-middle-click or type @key{S-RET} to view the
1345 link in another window. @key{TAB} goes to the next link, while
1346 @key{S-TAB} goes to the previous one.
1348 You can pick up hyperlinks using the @code{planner-annotation-as-kill}
1351 @defun planner-annotation-as-kill
1352 Create a context-sensitive hyperlink for the current buffer and copy
1353 it to the kill ring. When called with a prefix argument, prompt for
1354 the link display name.
1357 You can then paste it into any Planner buffer by using @kbd{M-x yank}
1358 or the keyboard shortcut.
1360 Alternatively, you can create hyperlinks by typing them directly, using
1361 the syntax defined by Muse. Anything inside double square brackets will
1362 be treated as a link. For example, if you type @samp{[[GroceryList]]} in
1363 a Planner buffer, you will end up with a link to a page called
1364 @samp{GroceryList}. @inforef{Implicit Links, Bare URLs WikiNames and
1365 InterWiki links, muse}, for more information about Muse syntax.
1367 Hyperlinks are a powerful feature of Planner. You can use them to
1368 hyperlink to mail, news, Web pages, and even IRC connections. See the
1369 section on @ref{Managing Your Information} to find out how to enable
1370 support for various parts of Emacs. Want to add a new hyperlink
1371 scheme? Check out the source code for examples or ask on the mailing
1374 @node Example Page, Review, Hyperlinks, Getting Started
1375 @comment node-name, next, previous, up
1376 @section Example Page
1377 @cindex example page
1378 @cindex planning page, example
1380 An example planner file is given below. You'll notice that Planner
1381 does not have a well-defined user interface. Rather, it's free-form
1382 and open, allowing you to adapt it to your preferences.
1385 ----------------------------------------------------------------------
1388 #B _ Join http://mail.gna.org/listinfo/planner-el-discuss/ (TaskPool)
1389 #B _ Browse through the Planner info manual (TaskPool)
1390 #B _ Add (plan) to the end of my ~/.emacs
1391 #B X Learn how to schedule a task (TaskPool)
1395 18:00 | 19:00 | Learn how to use Planner
1399 Notes are free-form. You can put anything you want into this.
1401 .#1 This is note number one
1403 Notes on note number one!
1405 .#2 This weird ".#2" syntax is used for allout.el enumerated lists
1407 It makes using allout-mode very handy.
1411 @node Review, , Example Page, Getting Started
1412 @comment node-name, next, previous, up
1417 @item @emph{Ideas for using planner more effectively:}
1421 Add @code{(plan)} to the end of your @file{~/.emacs} so that you are
1422 reminded about your tasks every day.
1425 Bind useful functions to shortcut keys and get used to creating tasks
1426 and notes from anywhere.
1429 Think about how you plan your day and look for ways to improve it. Ask
1430 the mailing list (@pxref{Getting Help}) for tips.
1433 Browse the rest of this manual, the source code, and other resources on
1434 the Net for tidbits you can use.
1439 @item @emph{Useful functions outside planner buffers:}
1442 @item @code{planner-create-task-from-buffer}
1443 @item @code{remember}
1444 @item @code{planner-goto-today}
1445 @item @code{planner-goto}
1449 @item @emph{Useful functions inside planner buffers:}
1452 @item @kbd{C-c C-t} (@code{planner-create-task-from-buffer})
1453 @item @kbd{C-c C-x} (@code{planner-task-done})
1454 @item @kbd{M-x planner-edit-task-description}
1457 @kbd{C-c C-c} (@code{planner-copy-or-move-task}), @kbd{M-x
1458 planner-copy-or-move-region}
1460 @item @kbd{M-x planner-replan-task}
1461 @item @kbd{M-x planner-delete-task}
1464 @key{M-p} (@code{planner-raise-task}) and @key{M-n}
1465 (@code{planner-lower-task})
1467 @item @key{C-M-p} (@code{planner-raise-task-priority}) and
1468 @key{C-M-n} (@code{planner-lower-task-priority}),
1469 @item @code{planner-replan-note}
1470 @item @code{planner-update-note}
1475 That's all you need to know in order to use Planner as a basic TODO and
1476 notes manager, but there's a whole lot more. Read through this manual
1477 and our mailing list archives (@pxref{Getting Help}) for lots of
1478 wonderful ideas about planning in Emacs!
1480 @node More about Planner, Managing Your Information, Getting Started, Top
1481 @comment node-name, next, previous, up
1482 @chapter More about Planner
1486 * More about Tasks::
1487 * More about Notes::
1488 * Making Files Pretty::
1490 * Interactive Lisp:: planner-lisp.el
1491 * Publishing:: planner-publish.el
1492 * Experimental Functions:: planner-experimental.el
1495 @node Navigation, More about Tasks, More about Planner, More about Planner
1496 @comment node-name, next, previous, up
1497 @section Starting with Day Pages
1499 @command{planner-goto-today} opens today's page. Day pages are named
1500 @samp{YYYY.MM.DD} and contain your notes for the day.
1502 You should see a file that looks like this:
1513 You can type anything you want into this file. You can add or delete
1514 sections. When you save, Emacs stores your information in
1515 @code{planner-directory}.
1517 Use the following commands to navigate through day pages:
1520 Start planning the day. If @code{planner-carry-tasks-forward} is
1521 non-nil, copy the most recent unfinished tasks to today's page, else
1522 open the most recent page.
1525 @defun planner-goto (@kbd{C-c C-j C-d})
1526 Prompt for a date using a calendar pop-up and display the
1527 corresponding day page. You can specify dates partially. The current
1528 year and month are used if omitted from the input. For example, if
1529 today is 2004.05.05, then
1532 @item @kbd{+1} is one day from now, or @samp{2004.05.06}
1533 @item @kbd{-1} is one day before now, or @samp{2004.05.04}
1534 @item @kbd{12} is equivalent to @samp{2004.05.12}
1535 @item @kbd{8.12} is equivalent to @samp{2004.08.12}
1536 @item @kbd{2005.08.12} is a full date specification
1539 In the calendar buffer, you can also left-click or press @key{RET} on
1540 a date to select it.
1543 @defun planner-goto-today (@kbd{C-c C-j C-j})
1544 Display today's page. Create the page if it does not yet exist.
1547 @defun planner-goto-tomorrow (@kbd{C-c C-j C-t})
1548 Goto the planner page days @var{after} the currently displayed date.
1549 If @var{days} is nil, go to the day immediately after the currently
1550 displayed date. If the current buffer is not a daily planner page,
1551 calculate date based on today.
1554 @defun planner-goto-yesterday (@kbd{C-c C-j C-y})
1555 Goto the planner page @var{days} before the currently displayed date.
1556 If @var{days} is nil, go to the day immediately before the currently
1557 displayed date. If the current buffer is not a daily planner page,
1558 calculate date based on today.
1561 @defun planner-goto-most-recent
1562 Go to the most recent day with planning info.
1565 @defun planner-goto-previous-daily-page
1566 Goto the last plan page before the current date.
1567 The current date is taken from the day page in the current
1568 buffer, or today if the current buffer is not a planner page.
1569 Do not create pages if they do not yet exist.
1572 @defun planner-goto-next-daily-page
1573 Goto the first plan page after the current date.
1574 The current date is taken from the day page in the current
1575 buffer, or today if the current buffer is not a planner page.
1576 Do not create pages if they do not yet exist.
1579 @defun planner-goto-plan-page page
1580 Opens @var{page} in the the @code{planner-project} Wiki. Use
1581 @code{planner-goto} if you want fancy calendar completion.
1584 @defun planner-show date
1585 Show the plan page for @var{date} in another window, but don't select
1586 it. If no page for @var{date} exists, return nil.
1590 @node More about Tasks, More about Notes, Navigation, More about Planner
1591 @comment node-name, next, previous, up
1592 @section More about Tasks
1593 @cindex tasks, more about
1595 This section is divided into three parts. In the first part, you can
1596 read about all the options, strategies and commands to help you
1597 efficiently add new tasks to your planner. In the second part, we'll go
1598 over all of the aspects of Planner that relate to organizing, editing,
1599 rescheduling and viewing the tasks you've already created. Finally,
1600 we'll cover some ways to step back and look at various reports and
1601 overviews that can be generated from your planner pages.
1603 You may also be interested in tracking time spent on tasks with
1604 @ref{Timeclock} and estimating project completion time with
1605 @ref{Schedule} (also see @pxref{schedule.el}).
1608 * Creating New Tasks::
1609 * Organizing Your Tasks::
1610 * Task Reports and Overviews::
1613 @node Creating New Tasks, Organizing Your Tasks, More about Tasks, More about Tasks
1614 @comment node-name, next, previous, up
1615 @subsection Creating New Tasks
1616 @cindex tasks, creating
1618 Planner makes it very easy to quickly add something to your list of
1619 tasks. Once you get used to the basics of
1620 @command{planner-create-task-from-buffer}, you might want to take a
1621 closer look at some things in Planner that can help you create new tasks
1622 in a way that fits with your system.
1627 * Task IDs:: planner-id.el
1628 * Cyclic Tasks:: planner-cyclic.el
1630 * Deadlines:: planner-deadline.el
1633 @node Creating a Task, Task Priorities, Creating New Tasks, Creating New Tasks
1634 @comment node-name, next, previous, up
1635 @subsubsection Creating a Task
1636 @cindex tasks, creating
1638 You can create a task from any buffer in Emacs by invoking
1639 @command{M-x planner-create-task-from-buffer}.
1641 This command does more than just add an item to your list of tasks. It
1642 also connects that item to some useful context information.
1644 If you create a task while viewing any buffer other than a Planner
1645 day page, Planner will associate the task with a hyperlink to that
1646 buffer. Try it now by creating a task from this Info buffer.
1649 @item @kbd{M-x planner-create-task-from-buffer}
1651 When prompted for the task name, enter @kbd{Learn how to change a task's
1652 status} and press @key{RET}.
1655 When prompted for the date, press @key{RET} to schedule the task for
1659 When prompted for the project page, press @key{RET} to accept the
1660 default page of @samp{TaskPool}. This is a page for tasks not connected
1665 Planner prompts you for two pieces of information when you ask it
1666 to create a task. First, it asks you when you would like to have the
1667 task show up in your planner. If you would like it to be scheduled for
1668 today, you can just hit @key{RET}. If you would like it to be
1669 scheduled for some day during the current month, you can just enter
1670 the date, without the month, like @samp{16}. If you would like it to
1671 be scheduled for some day in a future month of the current year, you
1672 can enter just the month and date, like @samp{06.16}. If you would
1673 like to schedule something for next year, then enter the full date,
1674 like @samp{06.16.2005}. If you do not want this task to appear on a
1675 day page at all, you can enter @samp{nil}.
1677 The second piece of information Planner asks for is the name of
1678 the project to associate the task with. In the above example, you
1679 associated the task with the project ``TaskPool'', which means that
1680 you did not want to associate the task with a particular project or
1681 goal in your life. Another way to do this is to answer the project
1682 prompt by entering @samp{nil}. But instead, you might enter
1683 @samp{LearnPlanner} as the project. This creates a new page called
1684 ``LearnPlanner'' in your planner directory and places an entry for the
1687 The task then exists in two places: once on your day page, to show how
1688 it fits into your daily work; and once on a project page, to show how
1689 it fits into your larger projects and goals. In the future you might
1690 add related tasks like, ``Memorize Planner keybindings''. These
1691 tasks might be scattered over weeks or months worth of day pages, but
1692 as long as you enter the same project name for each, you will have a
1693 way to look at them all together on a single project page.
1695 Planner also creates hyperlinks to enable you to easily move back
1696 and forth between the day page system and the project page
1697 system. Each task on a day page will have a hyperlink to its project
1698 page. Each task on a project page will have a hyperlink to its day
1701 After using Planner for a while, you may find yourself with quite
1702 a few project pages. Keep in mind that completion is enabled at the
1703 project prompt when you create a task, so hitting @kbd{SPC} or
1704 @kbd{TAB} at the prompt will show you a list of your current project
1707 Once the task is created, you are returned to the buffer you were
1708 working in again, Planner gets out of your way, and you can go on
1709 about your business. Later on, when you decide to actually work on
1710 that ``Memorize Planner keybindings'' task, you will be able to
1711 follow the hyperlink from that task on your day or project page
1712 directly to the relevant node in the Planner info file!
1714 By default, @command{M-x planner-create-task-from-buffer} creates
1715 medium-priority tasks, marked with the letter @samp{B}. But you can
1716 specify a particular priority or change the default (@pxref{Task
1719 You don't have to use @command{planner-create-task-from-buffer} to
1720 create tasks. You can also create new tasks manually by typing them
1721 directly on your day or project page in the format Planner expects. You
1722 can even still create hyperlinks by using Muse formatting as you
1723 manually type the new task (@pxref{Hyperlinks}). Keep in mind also that
1724 tasks do not have to be linked to any other page.
1726 For convenience, @command{planner-create-task-from-buffer} is bound to
1727 @kbd{C-c C-t} in Planner buffers. You can bind
1728 @command{planner-create-task-buffer} to a shortcut key. See the
1729 manual for your Emacs distribution to find out more about keybinding.
1731 @defun planner-create-task-from-buffer title date plan-page
1732 Create a new task named @var{title} on @var{date} based on the current
1735 With a prefix, associate the task with the current planner page. If
1736 you create a task on a date page, you will be prompted for a plan
1737 page. If you create a task on a plan page, you will be prompted for a
1738 day page. If nil is specified, the task is created only on the
1741 See @code{planner-create-task} for more information.
1743 The new task is created at the top or bottom of the first block of
1744 tasks on the scheduled day page (if any), depending on the value of
1745 @code{planner-add-task-at-end-flag}.
1748 @defun planner-create-task title date annotation plan-page
1749 Create a new task named @var{title} based on the current Wiki page.
1750 If @var{date} is non-nil, makes a daily entry on @var{date}, else
1751 makes an entry in today's planner page. It's assumed that the current
1752 Wiki page is the page you're using to plan an activity. Any time
1753 accrued to this task will be applied to that page's name in the
1754 timelog file, assuming you use timeclock (@pxref{Time Intervals, , ,
1755 Emacs, GNU Emacs Manual}). If @var{annotation} is non-nil, it will be
1756 used for the page annotation. If @var{plan-page} is non-nil, the task
1757 is associated with the given page.
1759 With a prefix, associate the task with the current planner page. If
1760 you create a task on a date page, you will be prompted for a plan
1761 page. If you create a task on a plan page, you will be prompted for a
1762 day page. If nil is specified, the task is created only on the
1765 You probably want to call @code{planner-create-task-from-buffer}
1768 The new task is created at the top or bottom of the first block of
1769 tasks on the scheduled day page (if any), depending on the value of
1770 @code{planner-add-task-at-end-flag}.
1773 @node Task Priorities, Task IDs, Creating a Task, Creating New Tasks
1774 @comment node-name, next, previous, up
1775 @subsubsection Task Priorities
1777 You can set the priority of a task when you create it, rather than
1778 waiting to adjust it after the fact. In order to do this, call the
1779 function corresponding to the priority you want. You probably want to
1780 bind these functions to some keys if you intend to use them much.
1783 @item @code{planner-create-high-priority-task-from-buffer}
1784 creates a task with priority @samp{A}.
1786 @item @code{planner-create-medium-priority-task-from-buffer}
1787 creates a task with priority @samp{B}.
1789 @item @code{planner-create-low-priority-task-from-buffer}
1790 creates a task with priority @samp{C}.
1793 Or, you can change the default priority of
1794 @command{planner-create-task-from-buffer} by customizing
1795 @var{planner-default-task-priority}.
1797 You can actually use just one general priority, but using more than
1798 one color-codes your tasks and gives you a better overview of your
1802 @node Task IDs, Cyclic Tasks, Task Priorities, Creating New Tasks
1803 @comment node-name, next, previous, up
1804 @subsubsection Task IDs
1805 @cindex @file{planner-id.el}, using
1808 After loading @file{planner.el}, make sure that @file{planner-id.el} is
1809 in your load path and add this to your @file{.emacs} (or @file{_emacs}):
1812 (require 'planner-id)
1815 This module modifies the behavior of @file{planner.el}, adding global
1816 task IDs so that tasks can be edited and updated. Planner IDs are of
1817 the form @samp{@{@{Identifier:Number@}@}}.
1821 @defopt planner-id-add-task-id-flag
1822 Non-nil means automatically add global task IDs to newly-created
1823 tasks. If nil, use @command{planner-id-add-task-id} to add IDs to
1824 existing tasks, or @command{planner-id-add-task-id-to-all} to add to
1825 all tasks on the current page.
1828 @defopt planner-id-update-automatically
1829 Non-nil means automatically update linked tasks whenever a page is
1830 saved. If nil, use @command{planner-update-task} to update the linked
1831 task. By default, linked tasks are automatically updated.
1834 @defopt planner-id-tracking-file
1835 File that contains ID tracking data. This file is automatically
1839 @subheading Functions
1841 The following interactive functions are defined in @file{planner-id.el}:
1843 @defun planner-id-jump-to-linked-task &optional info
1844 Display the linked task page. If @var{info} is specified, follow that
1848 @defun planner-id-add-task
1849 Add a task ID for the current task if it does not have one
1850 yet. Update the linked task page, if any.
1853 @defun planner-id-update-tasks-on-page &optional force
1854 Update all tasks on this page. Completed or cancelled tasks are not
1855 updated. This can be added to @code{write-file-functions}. If
1856 @var{force} is non-nil, completed and cancelled tasks are also
1860 @defun planner-id-add-task-id-to-all
1861 Add a task ID for all the tasks on the page. Update the linked page,
1865 @defun planner-id-search-id id
1866 Search for all occurrences of @var{id}.
1869 @defun planner-id-follow-id-at-point
1870 Display a list of all pages containing the ID at point.
1873 @defun planner-id-follow-id-at-mouse event
1874 Display a list of all pages containing the ID at mouse. @var{event} is
1878 @node Cyclic Tasks, Task Detail, Task IDs, Creating New Tasks
1879 @comment node-name, next, previous, up
1880 @subsubsection Cyclic Tasks
1881 @cindex @file{planner-cyclic.el}, using
1882 @cindex tasks, cyclic
1883 @cindex cyclic tasks
1884 @cindex recurring tasks
1886 If there are tasks that you have to do regularly, you can have Planner
1887 schedule those tasks automatically.
1889 Make sure that @file{planner-cyclic.el} is in your load path and add
1890 this to your @file{.emacs} (or @file{_emacs}):
1893 (require 'planner-cyclic)
1896 Create a diary file named @file{~/.diary.cyclic-tasks}
1897 (or the value of @code{planner-cyclic-diary-file}). Here is an example:
1900 Tuesday #B0 _ Study Japanese
1901 Friday #B0 _ Study Japanese (JapaneseStudies)
1904 The first will be a plain task, the second will be linked. The first
1905 line will automatically create its task every Tuesday, while the
1906 second will create it every Friday.
1908 You can schedule tasks in a variety of ways. This module uses the same
1909 syntax for specifying when tasks will be scheduled as the Emacs diary
1910 uses for appointments and events. See @ref{Date Formats, the GNU Emacs
1911 Manual, Date Formats,emacs, the GNU Emacs Manual}, and @ref{Sexp Diary
1912 Entries, the GNU Emacs Lisp Reference Manual, Sexp Diary
1913 Entries,elisp, the GNU Emacs Lisp Reference Manual}, for a full
1914 description of the possibilities.
1916 By default, planner-cyclic creates multiple tasks if you let tasks build
1917 up (that is, the next Tuesday rolls around and you @emph{still} haven't
1918 marked the task as done.) To turn off this behavior:
1921 (setq planner-cyclic-diary-nag nil)
1924 @subheading Functions
1926 @file{planner-cyclic-diary} includes the following interactive
1929 @defun planner-cyclic-create-tasks-maybe
1930 Maybe create cyclic tasks. This will only create tasks for future
1934 @node Task Detail, Deadlines, Cyclic Tasks, Creating New Tasks
1935 @comment node-name, next, previous, up
1936 @subsubsection Task Detail
1939 You may find your planner pages getting very full, so that you want to
1940 have one broad task entry be linked to a more specific list of
1941 sub-tasks. Or, maybe you want to have a number of notes linked to a
1944 @cindex tasks, meta-
1948 This can be done with targets. You can have a task that is really a
1952 #A1 _ Do things in RevelleLog#13 @{@{Tasks:101@}@} (RevelleLog)
1955 @samp{RevelleLog#13} could then be a list of sub-tasks in the form of
1956 a note, or any kind of note.
1958 Or, instead of pointing to a particular note on @samp{RevelleLog}, you
1959 could have the whole page be tasks that you enter in manually, without
1960 linking them to another page. You can just type them in like this:
1963 #A1 _ First specific thing to do
1966 This way, the tasks will only appear on this specific project page,
1967 and not on any daily page, so you only see them when you want to look
1968 up all of the specific tasks associated with @samp{#A1 _ Do things in
1969 RevelleLog @{@{Tasks:101@}@} (RevelleLog)}.
1971 As you can see, the ability to manually enter tasks is one of
1972 Planner's nicest features. It allows you to create tasks that are
1973 not assigned to a specific date (by manually entering them on a
1974 project page with no date) or to a specific project (by manually
1975 entering them on a day page with no project). Yet as long as you enter
1976 them using the syntax it understands, Planner will continue to
1977 recognize them as tasks.
1979 Another way to have a task not be connected to a particular date is to
1980 do @kbd{C-c C-c} (@code{planner-copy-or-move-task}) and specify
1981 @samp{nil} when asked for the date.
1983 If you would like to see a list of all of your unfinished scheduled
1984 tasks, do @kbd{M-x planner-list-unfinished-tasks}. It is only intended
1985 to give you an overview. Any editing you want to do, like marking tasks
1986 complete or editing their description, still needs to be done on one of
1987 the tasks' ``real'' planner pages.
1989 @node Deadlines, , Task Detail, Creating New Tasks
1990 @comment node-name, next, previous, up
1991 @subsubsection Deadlines
1992 @cindex tasks, deadlines for
1993 @cindex deadlines, task
1994 @cindex @file{planner-deadline.el}, using
1996 You can use @file{planner-deadline.el} to automatically recalculate
1997 days to a deadline by adding @code{(require 'planner-deadline)} to
1998 your @file{~/.emacs}. With the default setup, make your tasks of the
2002 #A0 _ Some task @{@{Deadline: 2004.09.12@}@}
2005 (Note: There must be at least one space after the colon.)
2007 After you run @code{planner-deadline-update} to update task descriptions,
2008 the task will be of the form
2011 #A0 _ Some task @{@{Deadline: 2004.09.12 - 2 days@}@}
2016 @defopt planner-deadline-regexp
2017 Regular expression for deadline data.
2018 The special deadline string should be regexp group 1. The
2019 date (YYYY.MM.DD) should be regexp group 2.
2022 @subheading Functions
2024 @defun planner-deadline-update
2025 Replace the text for all tasks with deadlines. Deadlines are of the
2026 form @samp{@{@{Deadline: YYYY.MM.DD@}@}} by default.
2029 @defun planner-deadline-change &optional date
2030 Change the deadline of current task to @var{date}. If @var{date} is nil,
2034 @node Organizing Your Tasks, Task Reports and Overviews, Creating New Tasks, More about Tasks
2035 @comment node-name, next, previous, up
2036 @subsection Organizing Your Tasks
2037 @cindex tasks, organizing
2040 Okay, now that you've gotten the hang of creating tasks, you're probably
2041 facing a really long list of things to do. How can you organize them so
2042 that they don't overwhelm you? Planner gives you a number of strategies
2043 for dealing with large numbers of tasks.
2046 @item Arrange your tasks in the rough order you're going to do them.
2047 @item Use #A, #B and #C task priorities to differentiate between
2048 high-priority, normal and low-priority tasks.
2049 @item Schedule your tasks onto different days.
2050 @item Group your tasks into plan pages.
2051 @item Don't schedule all your tasks.
2056 @item @emph{Task order}
2058 To remind yourself to do tasks in a certain order, simply edit the
2059 lines so that they're in the order you want. You can use normal
2060 editing commands like kill, yank and transpose-line to reorder the
2061 tasks, or use @key{M-p} (@code{planner-raise-task}) and @key{M-n}
2062 (@code{planner-lower-task}) to rearrange the tasks.
2064 @item @emph{Task priorities}
2066 By default, tasks are created with medium priority (@samp{#B}). You
2067 can make a task high-priority (@samp{#A}) or low-priority (@samp{#C})
2068 by manually editing the task and calling M-x planner-update-task to
2069 update the linked page. Alternatively, you can use @key{C-M-p}
2070 (@code{planner-raise-task-priority}) and @key{C-M-n}
2071 (@code{planner-lower-task-priority}) to modify the task and update the
2074 You can edit the priority of a task using @kbd{M-x
2075 planner-edit-task-priority}, or manually edit it and call @kbd{M-x
2076 planner-update-task} to update tasks on the linked page.
2078 @item @emph{Schedule your tasks on different days}
2080 You don't have to do everything today. Is this a task you would rather
2081 do tomorrow? Schedule it for then instead. You can specify @samp{+n}
2082 or @samp{-n} whenever you are asked for a date, where @var{n} is the
2083 number of days before or after the current file's date or today.
2084 Don't over-procrastinate things, though!
2086 @item @emph{Plan pages}
2088 Plan pages let you group related tasks and notes together for easy
2089 reference. For example, you could have a plan page for each major
2090 project or goal in your life, like @samp{GoodHealth} or
2091 @samp{FurtherStudies}.
2093 Although plan pages start by grouping everything under a @samp{*
2094 Tasks} header, you can organize your plan pages in different ways. For
2095 example, you can separate groups of tasks with blank lines, and
2096 Planner will sort tasks within each group.
2098 @item @emph{Tasks without dates}
2100 Plan pages also allow you to have undated tasks or tasks with no
2101 particular deadlines. This keeps your daily task list small and
2102 manageable while making it easier for you to find things to do if you
2103 have free time. Make sure you check your plan pages regularly so that
2104 you don't completely forget about them.
2106 For automated scheduling of the next task on a plan page after you
2107 complete a task, see the section in
2108 @uref{http://sacha.free.net.ph/notebook/emacs/planner-config.el} named
2109 ``Schedule next undated task from same project''.
2115 * Multiple Projects::
2118 * Carrying Over Unfinished Tasks::
2120 * Task Ranks:: planner-rank.el
2121 * Grouping Tasks:: planner-trunk.el
2124 @node Multiple Projects, Viewing Tasks, Organizing Your Tasks, Organizing Your Tasks
2125 @comment node-name, next, previous, up
2126 @subsubsection Associating Tasks with Multiple Projects
2127 @cindex multiple projects
2128 @cindex @file{planner-multi.el}, using
2130 You can use @file{planner-multi.el} to associate a task with more than
2131 one project. That way, you can easily keep GTD-style context lists as
2132 well as project-related lists.
2134 To use multiple projects, add the following to your @samp{~/.emacs}:
2137 (require 'planner-multi)
2140 Under GNU Emacs, you can specify multiple projects by separating them
2141 with a single space. For example, you can specify @kbd{planner doc}
2142 when creating a task to associate the task with those two projects.
2144 Under XEmacs, you can specify multiple projects by typing @kbd{RET}
2145 after each entry and terminating the list with another @kbd{RET}. For
2146 example, to specify @kbd{planner} and @kbd{doc}, you would type
2147 @kbd{planner RET doc RET RET} at the prompt.
2149 If you want to see an overview of all of your tasks as well as
2150 project- or context-specific lists, you can set
2151 @code{planner-multi-copy-tasks-to-page} to your overview page(s). For
2152 example, set it to @samp{TaskPool} to be able to see an overview of
2153 all of your unfinished tasks. You can also set this to multiple pages
2154 such as @samp{[[TasksByProject][p]] [[TasksByContext][c]]} and use
2155 @file{planner-trunk.el} to sort and organize tasks for easy reference.
2156 (@pxref{Grouping Tasks})
2160 @defopt planner-multi-copy-tasks-to-page
2161 Automatically copy newly-created tasks to the specified page.
2164 By default, tasks are removed from
2165 @code{planner-multi-copy-tasks-to-page} when you call
2166 @code{planner-task-done} or @code{planner-task-cancelled}. If you
2167 prefer to keep a copy of the task, remove
2168 @code{planner-multi-remove-task-from-pool} from
2169 @code{planner-mark-task-hook}.
2171 If you want to use a different separator instead of spaces, customize
2172 the @code{planner-multi-separator} variable.
2174 @defopt planner-multi-separator
2175 String that separates multiple page references.
2177 For best results, this should be something recognized by
2178 @code{muse-link-at-point} so that links are highlighted
2182 @node Viewing Tasks, Modifying Tasks, Multiple Projects, Organizing Your Tasks
2183 @comment node-name, next, previous, up
2184 @subsubsection Viewing tasks
2185 @cindex tasks, viewing
2187 Review the tasks scheduled for today by typing @kbd{M-x
2188 planner-goto-today}. If you created the task from the previous
2189 section in this tutorial, you should see a line that looks like
2192 #A _ Learn how to change a task's status from Tasks (TaskPool)
2195 If you have @code{planner-use-task-numbers} set to non-nil, you will see
2196 something like the following instead.
2199 #A0 _ Learn how to change a task's status from Tasks (TaskPool)
2202 From left to right, these are what the symbols mean:
2205 @item @samp{A} - Priority. A (high)
2207 @samp{0} - Priority number. It is calculated whenever you save the file
2208 or call @command{planner-renumber-tasks}, provided that
2209 @code{planner-use-task-numbers} is non-nil. Tasks are numbered in
2210 ascending order according to priorities.
2211 @item @samp{_} - Status. _ (unfinished)
2214 If you click on @samp{Tasks} or press @key{RET} while your cursor is
2215 in the link, Emacs will display the previous info page.
2217 If you select @samp{TaskPool}, Emacs will display the @samp{TaskPool}
2218 plan page. Plan pages organize your tasks and notes about a project
2221 @subheading Functions
2223 You can use @command{planner-seek-next-unfinished-task} to move to the
2224 next unfinished task on the current page.
2226 @defun planner-list-tasks-with-status status &optional pages
2227 Display all tasks that match the STATUS regular expression on all day
2228 pages. The PAGES argument limits the pages to be checked in this
2232 @item @code{t}: check all pages
2233 @item regexp: search all pages whose filenames match the regexp
2234 @item list of page names: limit to those pages
2235 @item alist of page/filenames: limit to those pages
2238 Called interactively, this function will search day pages by
2239 default. You can specify the start and end dates or leave them as
2240 nil to search all days. Calling this function with an interactive
2241 prefix will prompt for a regular expression to limit pages.
2242 Specify @samp{.} or leave this blank to include all pages.
2244 This function could take a long time.
2247 @defun planner-list-unfinished-tasks &optional pages
2248 Display all unfinished tasks. @var{pages} follows
2249 planner-list-tasks-with-status.
2252 @defun planner-jump-to-linked-task task-info
2253 Display the task page linked to by the current task or
2257 @node Modifying Tasks, Carrying Over Unfinished Tasks, Viewing Tasks, Organizing Your Tasks
2258 @comment node-name, next, previous, up
2259 @subsubsection Modifying Tasks
2260 @cindex tasks, modifying
2261 @cindex tasks, editing
2263 To select a task, move your cursor to the line containing the task.
2265 Change a task's priority (@samp{A}, @samp{B} or @samp{C}) by editing
2266 the line. @samp{#A} tasks are important. @samp{#B} are medium
2267 priority. @samp{#C} are low priority. Whenever you save the file or
2268 call @kbd{M-x planner-fix-tasks}, tasks are sorted and numbered
2269 according to priority and status.
2271 Change a task's status by calling one of the following functions:
2274 @item planner-task-in-progress @samp{o} (@kbd{C-c C-z})
2275 @item planner-task-done @samp{X} (@kbd{C-c C-x})
2276 @item planner-task-cancelled @samp{C} (@kbd{C-c C-S-x})
2277 @item planner-task-delegated @samp{D}
2278 @item planner-task-pending @samp{P}
2279 @item planner-task-open @samp{_}
2282 After changing the status using a function, look at the
2283 @samp{TaskPool} plan page. The task is also updated on the linked
2284 page. If you changed the task status manually by replacing the status
2285 with another character, you will need to call
2286 @command{planner-update-task} to update the linked page.
2288 To reschedule a task, call @command{planner-copy-or-move-task} (@kbd{C-c
2289 C-c}) and choose a new date. You can mark a region and type @kbd{M-x
2290 planner-copy-or-move-region} to reschedule all the contained tasks to a
2291 different date. Enter @samp{nil} for the date if you don't want the
2292 task or group of tasks to appear on any date page at all anymore. This
2293 is a good way to ``de-schedule'' a task for the time being, but still
2294 keep it linked to a plan page for possible future scheduling.
2296 To change the plan page associated with a task, call
2297 @command{planner-replan-task}. Enter @samp{nil} for the plan page if
2298 you don't want the task to appear on any plan page anymore. If you
2299 precede the command with a prefix argument, the text of the original
2300 plan page will appear in the prompt for easy editing.
2302 Since the same task may exist on two or more pages, such as a date page
2303 and a plan page, it is dangerous to edit the description of the task by
2304 hand. You should not do it unless you want to make the exact same
2305 changes on all its linked pages.
2307 Instead of doing this by hand, you should use
2308 @command{planner-edit-task-description}. This will prompt you for the
2309 changes to the task description and then update all the other pages to
2310 which the task is linked. Or, you can just use
2311 @command{planner-delete-task} to remove the task from both pages, and
2312 then create it again with the new desired description.
2314 To remind yourself to do tasks in a certain order, simply edit the
2315 lines so that they're in the order you want.
2316 @command{planner-raise-task} and @command{planner-lower-task} update
2317 the priorities on linked pages automatically. You can organize tasks
2318 into groups by putting a blank line between groups of tasks.
2319 Planner will maintain the groupings and only sort the tasks within
2322 @subheading Functions
2324 @defun planner-replan-task page-name
2325 Change or assign the plan page for the current task. @var{page-name}
2326 is the new plan page for the task. Use
2327 @code{planner-copy-or-move-task} if you want to change the date. With a
2328 prefix, provide the current link text for editing.
2331 @defun planner-raise-task-priority
2332 Change a low-priority task to a medium-priority task and a
2333 medium-priority task to a high-priority task (C to B to A).
2336 @defun planner-lower-task-priority
2337 Change a high-priority task to a medium-priority task and a
2338 medium-priority task to a low-priority task (A to B to C).
2341 @defun planner-raise-task arg
2342 Move a task up @var{arg} steps. By default, @var{arg} is 1.
2345 @defun planner-lower-task arg
2346 Move a task down @var{arg} steps. By default, @var{arg} is 1.
2349 @defun planner-edit-task-description description
2350 Change the description of the current task, updating the linked page
2354 @defun planner-delete-task
2355 Delete this task from the current page and the linked page.
2358 @defun planner-update-task
2359 Update the current task's priority and status on the linked page.
2360 Tasks are considered the same if they have the same description.
2361 This function allows you to force a task to be recreated if it
2362 disappeared from the associated page.
2364 Note that the text of the task must not change. If you want to be able
2365 to update the task description, see @code{planner-edit-task-description}
2366 or @file{planner-id.el}.
2369 See @command{planner-install-extra-task-keybindings} for additional
2370 task-related shortcuts.
2372 @node Carrying Over Unfinished Tasks, Task Numbering, Modifying Tasks, Organizing Your Tasks
2373 @comment node-name, next, previous, up
2374 @subsubsection Carrying Over Unfinished Tasks
2375 @cindex tasks, carrying over
2377 Sometimes you won't be able to cross off all the tasks on your list.
2378 Planner makes it easy for you to keep track of things you still have
2379 to do by automatically rescheduling unfinished tasks from the past few
2380 days. By default, the @command{plan} command searches for unfinished
2381 tasks from the last three days and reschedules them onto today. If you
2382 open Planner every day, this should cover weekends easily.
2384 It's a good idea to start Planner whenever you start Emacs. That way,
2385 Planner can help remind you about today's tasks, appointments, and other
2386 things. To automatically start Planner whenever you start up Emacs, add
2387 the following code to the end of your @file{~/.emacs}:
2393 Now, every time you start Emacs (which should be more or less once a
2394 day), you'll see today's page. If you don't finish all the tasks today,
2395 you'll see them again tomorrow.
2397 It's a good idea to start Planner every time you start Emacs so that
2398 you get reminded about your task list. If you prefer to start Planner
2399 manually, remember to call @kbd{M-x plan} every so often to make sure
2400 that you don't forget any unfinished tasks. Safe in the knowledge that
2401 Planner tasks won't slip through the cracks (unlike little slips of
2402 paper that will invariably get mislaid), you can then get on with the
2405 If your increased productivity with Planner leads to a well-deserved
2406 two-week vacation, then you'll need to tell Planner to search more days
2407 for unfinished tasks. By using @kbd{M-x plan}, you can automatically
2408 bring forward tasks over a given number of days or even scan all the
2409 days since time immemorial. @kbd{C-u 15 M-x plan} reschedules all
2410 unfinished tasks from the last 15 days. @kbd{C-u -1 M-x plan} checks all
2411 of your past day pages for unfinished tasks.
2413 Like everything else in Planner, you can adapt @kbd{M-x plan} to your
2414 particular way of life. For example, if you find yourself starting up
2415 Emacs and Planner every day--including weekends--because it's just so
2416 much fun, you can set the @code{planner-carry-tasks-forward} to 1.
2417 This can make your Emacs startup marginally faster. On the other hand,
2418 if you normally start Emacs once a week, you can set it to 7 or 8. If
2419 you're worried about tasks dropping off your radar, you can set it to
2420 0. You can set the value of @var{planner-carry-tasks-forward} either
2421 with @key{M-x customize-variable RET planner-carry-tasks-forward RET},
2422 or by putting @code{(setq planner-carry-tasks-forward 3)} (replacing
2423 @code{3} with the value appropriate for what you want) in your
2424 @file{~/.emacs} file.
2426 On the other hand, you might prefer to reschedule tasks yourself. If
2427 you set @code{planner-carry-tasks-forward} to @code{nil}, then
2428 @command{M-x plan} and @code{(plan)} will bring you to the most recent
2429 page with unfinished tasks if there is no page for today. You can then
2430 use @command{planner-copy-or-move-task} and
2431 @command{planner-copy-or-move-region} to reschedule tasks. This is
2432 probably more hassle than it's worth, though, so let Planner take care
2437 @defopt planner-carry-tasks-forward
2438 If non-nil, carry unfinished tasks forward automatically.
2439 If a positive integer, scan that number of days in the past.
2440 If 0, scan all days for unfinished tasks.
2441 If t, scan one day in the past (old behavior).
2442 If nil, do not carry unfinished tasks forward.
2445 @subheading Functions
2447 @defun plan &optional force-days
2448 Start your planning for the day, carrying unfinished tasks forward.
2450 If @var{force-days} is a positive integer, search that many days in the
2451 past for unfinished tasks.
2452 If @var{force-days} is @code{0} or @code{t}, scan all days.
2453 If @var{force-days} is @code{nil}, use the value of
2454 @code{planner-carry-tasks-forward} instead, except t means scan only
2459 @defun planner-copy-or-move-task date force
2460 Reschedule the task for @var{date}. If @var{force} is non-nil, the
2461 task is moved regardless of status. It also works for creating tasks
2462 from a Note. Use @code{planner-replan-task} if you want to change the
2463 plan page in order to get better completion.
2466 @defun planner-copy-or-move-region beg end date muffle-errors
2467 Move all tasks from @var{beg} to @var{end} to @var{date}.
2468 @code{planner-copy-or-move-region} will copy or move all tasks from
2469 the line containing @var{beg} to the line just before @var{end}. If
2470 @var{muffle-errors} is non-nil, no errors will be reported.
2473 @node Task Numbering, Task Ranks, Carrying Over Unfinished Tasks, Organizing Your Tasks
2474 @comment node-name, next, previous, up
2475 @subsubsection Task Numbering
2477 By default, tasks are numbered according to their position on the
2478 page. Task numbers allow you to refer to tasks using Muse links.
2479 For example, the @samp{#A1} task in @file{2004.08.16} can be referred to
2480 as @samp{2004.08.16#A1}.
2482 Note that task numbers change every time you re-sort and re-number tasks
2483 with @code{planner-fix-tasks}. As a result, they are only reliable for
2484 references to past tasks.
2486 If you find yourself not using this functionality, you can turn off task
2487 numbers by using the following option.
2491 @defopt planner-use-task-numbers
2492 Non-nil means use task numbers when creating tasks. This allows you
2493 to refer to past tasks if your tasks are numbered appropriately.
2494 If you set this to nil, you can save space in your plan files.
2497 @node Task Ranks, Grouping Tasks, Task Numbering, Organizing Your Tasks
2498 @comment node-name, next, previous, up
2499 @subsubsection Task Ranks
2500 @cindex ranking tasks
2501 @cindex tasks, ranking
2502 @cindex @file{planner-rank.el}, using
2504 @file{planner-rank.el} models Franklin Covey's Urgency and Importance
2505 principle. When you think about a task, there are two aspects in
2506 consideration: Urgency and Importance. You may want to do the most
2507 urgent things first, like answering an email, or you may want to do
2508 the most important things first, like reading this manual. Or much
2509 better, balance Urgency and Importance and decide what to do.
2511 @file{planner-rank.el} can help you balance.
2513 Urgency and Importance are both measured by scores from 0-9. The
2514 higher the score, the more you want to do it first. 9 stands for ``I
2515 should have done this'' and 0 stands for ``I can forget this''.
2517 If you are using the planner @ref{Deadlines} feature, the Urgency
2518 score is automatically calculated from how many days are left to meet
2519 the deadline. By default, it will score 9 if the task is overdue and 0
2520 if the deadline is years away. Please refer to the docstring of
2521 @code{planner-rank-deadline-urgency-map-list} for detail.
2523 The task rank is calculated from Urgency and Importance scores. As
2524 different people balance urgency and importance differently, a number
2525 of @code{planner-rank-calculate-rank-*} functions are provided. The
2526 algorithms vary from a simple average to something like a weighted
2527 root mean square deviation.
2529 The aggressive versions of these functions
2530 (@code{planner-rank-calculate-rank-*-aggressive}) will make sure if
2531 one of Urgency and Importance is high, the resulting rank will be high
2532 as well. @code{planner-rank-calculate-rank-weighted-*} functions weigh
2533 the Urgency and Important scores depending on
2534 @code{planner-rank-importance-vs-urgency-factor}.
2536 Call @code{planner-rank-test-algorithm} on each of the functions and
2537 check the result tables to see which one you like most, and set it to
2538 @code{planner-rank-rank-calculate-function}. Alternatively, accept the
2539 defaults and tweak them when you get a better feel for ranking.
2541 Once the Rank is calculated, the @ref{Task Priorities} will be
2542 automatically reset. If the Rank is greater than or equal to
2543 @code{planner-rank-priority-A-valve}, the task priority will be
2544 @samp{A}, if the Rank is between @code{planner-rank-priority-A-valve}
2545 and @code{planner-rank-priority-B-valve}, the priority will be @samp{B},
2546 else it will be @samp{C}.
2548 After setting the task importance and deadline, you can leave it as
2549 is. As the deadline approaches, the task priority will automatically
2550 be raised and the task re-colored to catch your eyes.
2552 If you are using @code{planner-sort-tasks} (see @pxref{Making Files
2553 Pretty}), you can set @code{planner-sort-tasks-key-function} to one of
2554 @code{planner-sort-tasks-by-rank},
2555 @code{planner-sort-tasks-by-importance}, and
2556 @code{planner-sort-tasks-by-urgency}.
2560 @defopt planner-rank-change-hook
2561 Functions to run after @code{planner-rank-change}.
2564 @defopt planner-rank-priority-A-valve
2565 Tasks with rank greater than or equal to this value will be set to
2569 @defopt planner-rank-priority-B-valve
2570 Tasks with rank greater than or equal to this value and less than
2571 @code{planner-rank-priority-A-valve} will be set to priority
2572 @samp{B}. Tasks with rank less than this value will be set to priority
2576 @defopt planner-rank-deadline-urgency-map-list
2577 Defines how to calculate the Urgency score according to how many days
2578 are left to meet the deadline.
2581 @defopt planner-rank-default-importance
2582 Default importance value for newly added rank.
2585 @defopt planner-rank-default-urgency
2586 Default urgency value for newly added rank.
2589 @defopt planner-rank-importance-vs-urgency-factor
2590 How much do you think importance is more ``important'' than urgency.
2591 This will be used in @code{planner-rank-calculate-rank-weighted-*}
2595 @defopt planner-rank-rank-calculate-function
2596 Define the function called to calculate rank.
2599 @subheading Functions
2601 @defun planner-rank-change &optional importance urgency
2602 Set the Importance and Urgency of the current task.
2605 @defun planner-rank-update-current-task
2606 Recalculate rank for the current task.
2609 @defun planner-rank-update-all
2610 Recalculate rank for all tasks in the current page
2613 @defun planner-rank-update-all
2614 Recalculate rank for all tasks in the current page
2617 @node Grouping Tasks, , Task Ranks, Organizing Your Tasks
2618 @comment node-name, next, previous, up
2619 @subsubsection Grouping Tasks with planner-trunk.el
2620 @cindex grouping tasks
2621 @cindex tasks, grouping
2622 @cindex @file{planner-trunk.el}, using
2624 @file{planner-trunk.el} helps you automatically group tasks according
2625 to a set of rules. It sorts and splits your tasks, adding a blank line
2626 between groups of tasks. For example, if today's page looks like this:
2631 #B _ Buy milk (GroceryShopping)
2632 #B _ Learn how to use planner-trunk (PlannerMode)
2633 #B _ Buy a notebook (Bookstore)
2634 #B _ Buy cereal (GroceryShopping)
2635 #B _ Set up my own planner-trunk rules (PlannerMode)
2636 #B _ Customize my stylesheet (MuseMode)
2637 #B _ Go for a health checkup (BetterHealth)
2641 then you might want to group the tasks into: planner and muse,
2642 shopping list, and other items. If you set up the appropriate rules by
2643 customizing @code{planner-trunk-rule-list}, @file{planner-trunk.el}
2644 can automatically rewrite that section line this:
2649 #B _ Learn how to use planner-trunk (PlannerMode)
2650 #B _ Set up my own planner-trunk rules (PlannerMode)
2651 #B _ Customize my stylesheet (MuseMode)
2653 #B _ Buy milk (GroceryShopping)
2654 #B _ Buy a notebook (BookstoreShopping)
2655 #B _ Buy cereal (GroceryShopping)
2657 #B _ Go for a health checkup
2661 In this case, you would set @code{planner-trunk-rule-list}
2662 to @code{(("." nil ("PlannerMode\\|MuseMode" "Shopping")))}.
2664 You can load @file{planner-trunk} with @kbd{M-x load-library RET
2665 planner-trunk RET} or add @code{(require 'planner-trunk)}. If you're
2666 not yet comfortable with Emacs Lisp, you can use @kbd{M-x
2667 customize-variable RET planner-trunk-rule-list RET} to edit this rule
2668 using an easy-to-use interface.
2670 WARNING: Do not keep non-task information in the Tasks section.
2671 planner-trunk will delete @strong{all} non-task lines from the Tasks
2672 section of your plan page in the process of grouping the tasks.
2674 After you set up @code{planner-trunk-rule-list}, use @command{M-x
2675 planner-trunk-tasks} to try out your rules until you're satistfied.
2677 If you want to do this automatically, you can use @code{(add-hook
2678 'planner-mode-hook 'planner-trunk-tasks)} to trigger it automatically
2679 whenever you open a Planner page.
2681 @node Task Reports and Overviews, , Organizing Your Tasks, More about Tasks
2682 @subsection Task Reports and Overviews
2683 @cindex task reports
2684 @cindex task overviews
2685 @cindex reports, task
2686 @cindex overviews, task
2687 @cindex reports, accomplishment
2688 @cindex tasks, overview of
2690 Planner provides a number of different ways to generate different
2691 presentations of your tasks.
2694 * Accomplishments:: planner-accomplishments.el
2695 * Status Reports:: planner-report.el
2696 * Task Overviews:: planner-tasks-overview.el
2698 * planner-registry:: Keep track of annotations
2699 * planner-zoom:: View and navigate tasks by time period
2702 @node Accomplishments, Status Reports, Task Reports and Overviews, Task Reports and Overviews
2703 @comment node-name, next, previous, up
2704 @subsubsection Generating Daily Accomplishment Reports
2705 @cindex reports, accomplishment
2706 @cindex @file{planner-accomplishments.el}, using
2707 @cindex tasks, overview of
2708 @cindex task reports
2709 @cindex reports, task
2710 @cindex overviews, task
2711 @cindex task overviews
2713 You can use @file{planner-accomplishments.el} to get a summary of your
2714 task activity for a particular day. The report is grouped by status
2715 and plan (on day pages) or date (on plan pages). An example report
2719 Link | Unfinished | In progress | Delegated | Completed | Total
2720 nil | 1 | 0 | 0 | 6 | 7
2721 TaskPool | 1 | 1 | 0 | 3 | 5
2722 Planner | 0 | 0 | 1 | 1 | 2
2723 SchoolWork | 0 | 0 | 0 | 1 | 1
2724 Total | 2 | 1 | 1 | 11 | 15
2727 This lets you see how you balance your time between your projects.
2731 There are currently two ways to use @file{planner-accomplishments.el}.
2733 @item Displaying a temporary buffer
2735 You can call @code{planner-accomplishments-show} to display a buffer
2736 containing the current page's accomplishment report.
2738 @item Rewriting sections of your planner
2740 Choose this approach if you want accomplishment reports to be in
2741 their own section and you would like them to be readable in your
2742 plain text files even outside Emacs. Caveat: The accomplishment
2743 section should already exist in your template and will be rewritten
2746 To use, set @code{planner-accomplishments-section} to the name of the
2747 section to rewrite (default: @samp{Accomplishments}). If you want
2748 rewriting to be automatically performed, call
2749 @code{planner-accomplishments-insinuate}. The accomplishments will be
2750 rewritten whenever you save a planner page. If you want rewriting to
2751 be manual, call @code{planner-accomplishments-update}.
2757 @defopt planner-accomplishments-section
2758 Header for the accomplishments section in a plan page.
2759 Used by @code{planner-accomplishments-update}.
2762 @defopt planner-accomplishments-status-display
2763 Alist of status-label maps also defining the order of display.
2764 Used by @code{planner-accomplishments-format-table}.
2767 @subheading Functions
2769 @defun planner-accomplishments-insinuate ()
2770 Automatically call @code{planner-accomplishments-update} when saving
2771 tasks in @code{planner-mode} buffers.
2774 @defun planner-accomplishments-update ()
2775 Rewrite @code{planner-accomplishments-section} with a summary of tasks
2779 @defun planner-accomplishments-show ()
2780 Display a buffer with the current page's accomplishment report.
2783 @node Status Reports, Task Overviews, Accomplishments, Task Reports and Overviews
2784 @comment node-name, next, previous, up
2785 @subsubsection Status Reports
2786 @cindex status reports
2787 @cindex reports, status
2788 @cindex @file{planner-report.el}, using
2790 @file{planner-report.el} creates a status report for a given timespan.
2791 The report itself is just another Planner page in your planner
2792 directory. Once generated, it contains tasks and notes culled from
2793 active project pages. Tasks are only shown if they are incomplete or
2794 were completed within the timespan. Notes are shown if they were
2795 created during the timespan. Tasks and notes are grouped together under
2796 a heading for their corresponding project.
2798 The idea is you have one of these status reports generated periodically
2799 (say, every couple of weeks). Perhaps you use cron to run them
2800 automatically and then mail you a reminder that they've been done. Then
2801 you can edit the page, adding verbiage where it is needed and removing
2802 irrelevant items. This editing process is as easy as editing any other
2803 Planner page. Finally, you can publish the page along with the rest of
2804 your planner using @kbd{M-x muse-project-publish}.
2806 If you use planner-authz.el, you can tell planner-report.el only to
2807 consult project pages that a given list of users
2808 (@var{planner-report-authz}) can access when generating the report. For
2809 example, if you're preparing a status report for your boss, add yourself
2810 and him to @var{planner-report-authz}. The resulting status report will
2811 only contain information the two of you are supposed to have access to,
2812 and the report itself will be similarly restricted.
2814 @subheading Getting started
2816 Add the following to your .emacs file:
2819 (require 'planner-report)
2822 Then you can use the following command to generate a status report:
2825 M-x planner-report-generate
2828 You will be prompted for a beginning and ending date, and then the
2829 status report will be generated. You can then edit it to your liking
2830 and publish it just like you would the rest of your planner.
2834 @defopt planner-report-authz
2835 List of users a status report should be restricted to.
2836 When status reports are generated, only planner pages accessible
2837 by these users will be consulted, and the resulting status report
2838 will be similarly restricted.
2841 @defopt planner-report-pretty-print-plan-pages
2842 If non-nil, pretty print plan pages.
2843 If nil, leave page names as-is.
2844 This requires that @file{muse-wiki.el} be loaded to work properly.
2847 @defopt planner-report-remove-task-numbers
2848 Remove task numbers when generating status reports.
2851 @defopt planner-report-replace-note-numbers
2852 If non-nil, a string with which to replace note numbers when
2853 generating status reports.
2856 @defopt planner-report-unfinished-offset
2857 If non-nil, the offset in days from the current date of
2858 unfinished tasks to include in the status report. If nil,
2859 include all unfinished tasks.
2862 @subheading Functions
2864 @defun planner-report-generate begin end
2865 Generate a status report spanning a period from @var{begin} to @var{end}.
2866 @var{begin} and @var{end} are in the format YYYY.MM.DD.
2869 @node Task Overviews, <tasks> tag, Status Reports, Task Reports and Overviews
2870 @comment node-name, next, previous, up
2871 @subsubsection Seeing an Overview of Tasks
2872 @cindex tasks, overview of
2873 @cindex task reports
2874 @cindex reports, task
2875 @cindex overviews, task
2876 @cindex task overviews
2877 @cindex @file{planner-tasks-overview.el}, using
2879 You can see a list of tasks with @file{planner-tasks-overview.el}.
2880 Seeing how you've scheduled tasks over the next few days can help you
2881 decide when to schedule another task. Table entries will be of the form
2883 @var{date} | @var{link} | @var{priority} @var{status} | @var{task-description}
2885 @subheading Functions
2887 To display the tasks between a set of day pages, use
2889 @defun planner-tasks-overview start end
2890 Display an overview of your tasks from @var{start} to @var{end}. If
2891 @var{start} is nil, start from the very first day page. If @var{end}
2892 is nil, include the very last day page. You can use
2893 @code{planner-expand-name} shortcuts here, like @kbd{+1} or @kbd{-1}.
2894 Pressing @key{RET} at the prompt will use today.
2896 Once in a @code{planner-tasks-overview} buffer, you can use
2897 the keyboard shortcut @key{o} to change the overview period.
2900 You can sort the task display with the following functions:
2902 @defun planner-tasks-overview-sort-by-date
2903 Sort the tasks by date. Keyboard shortcut: @key{1}
2906 @defun planner-tasks-overview-sort-by-plan
2907 Sort the tasks by associated plan page. Keyboard shortcut: @key{2}
2910 @defun planner-tasks-overview-sort-by-priority
2911 Sort the tasks by priority. Keyboard shortcut: @key{3}
2914 @defun planner-tasks-overview-sort-by-status
2915 Sort the tasks by status. Keyboard shortcut: @key{4}
2918 You can jump to linked tasks with
2920 @defun planner-tasks-overview-jump other-window
2921 Display the current task. If a prefix argument is supplied, show the
2922 task in another window. Keyboard shortcut: @key{j}
2925 @defun planner-tasks-overview-jump-other-window
2926 Display the current task in another window. Keyboard shortcut: @kbd{C-u j}
2929 You can view a summary of the tasks in your plan pages with
2931 @defun planner-tasks-overview-show-summary &optional file-list
2932 Count unscheduled, scheduled, and completed tasks for FILE-LIST. If
2933 called with an interactive prefix, prompt for the plan page(s) to
2934 display. Load @file{planner-multi.el} to be able to specify multiple
2940 @key{TAB}, @kbd{SHIFT-TAB} and @key{RET} navigate links in the usual
2943 @node <tasks> tag, planner-registry, Task Overviews, Task Reports and Overviews
2944 @subsubsection <tasks> tag
2946 @cindex task reports
2947 @cindex reports, task
2948 @cindex overviews, task
2949 @cindex task overviews
2950 @cindex tasks, overview of
2952 @samp{<tasks>} is replaced by a report of tasks over all day pages in
2953 published pages (@pxref{Publishing}).
2956 All incomplete tasks
2969 Warning: this function can be slow, as it checks all the day pages!
2971 @node planner-registry, planner-zoom ,<tasks> tag, Task Reports and Overviews
2972 @comment node-name, next, previous, up
2973 @section planner-registry
2974 @cindex @file{planner-registry.el}, using
2976 The @file{planner-registry} module provides a way to keep track of all
2977 the URLs in your projects, and to list them depending on the current
2978 buffer. The URLs are defined in @code{muse-url-protocols} module from
2981 If a URL has been created by @code{planner-create-task-from-buffer},
2982 going to that buffer and calling @code{planner-registry-show} will show
2983 you where Planner put the URL.
2985 @subheading Getting started
2987 To begin using @file{planner-registry}, add the following to your
2988 Planner configuration file.
2991 (require 'planner-registry)
2992 (planner-registry-initialize)
2995 You must put it after the place where Planner has been loaded in your
2998 If you want the registry to be updated each time you save a Planner
2999 file, add the following to your Planner configuration.
3002 (planner-registry-insinuate)
3005 If you don't want to update the registry each time a file is written,
3006 you can do it manually with @code{planner-registry-update}: it will
3007 update the registry for saved Planner/Muse buffers only.
3009 @file{planner-registry} does not define any keybindings by default. Its
3010 most useful interactive function is @code{planner-registry-show}.
3012 @subheading Example usage
3014 Say for example that you created a task from an e-mail. Go to that
3015 e-mail and call @code{planner-registry-show}: it will open a new buffer
3016 displaying the files (in a muse links format) where a link to this
3017 e-mail has been added.
3021 @file{planner-registry} defines the following options.
3023 @defopt planner-registry-file
3024 The file where @file{planner-registry} stores its URL registry.
3027 @defopt planner-registry-min-keyword-size
3028 The minimum size for keywords.
3031 @defopt planner-registry-max-keyword-size
3032 The maximum size for keywords.
3035 @defopt planner-registry-max-number-of-keywords
3036 The maximum number of keywords.
3039 @defopt planner-registry-ignore-keywords
3040 A list of keywords to ignore.
3043 @defopt planner-registry-show-level
3044 Level used by the @code{planner-registry-show} function.
3045 0 means that this function shows only exact matches.
3046 1 means that this function also shows descriptive matches.
3047 2 (or more) means that this function also shows fuzzy matches.
3050 @node planner-zoom, , planner-registry, Task Reports and Overviews
3051 @comment node-name, next, previous, up
3052 @section planner-zoom
3053 @cindex @file{planner-zoom.el}, using
3054 @cindex view, weekly
3055 @cindex view, quarterly
3056 @cindex view, monthly
3057 @cindex view, yearly
3059 When assessing where you stand in relation to the tasks you have set
3060 out for yourself, you might want a way to survey those tasks in groups
3061 divided by time periods, like by the week or by the month. You could
3062 create all of these overview pages by hand, but if you like to have
3063 this kind of overview frequently, you might find manually creating
3064 such pages to be tedious and time consuming.
3066 @file{planner-zoom} is an optional module designed to make it easy to
3067 view your task information grouped by year, quarter, month, week or
3070 To install this module, just load it in your @file{.emacs} (or
3074 (require 'planner-zoom)
3077 This module will recognize planner pages named according to the
3086 @file{2006.Quarter2}
3092 @file{2006.January.Week3}
3099 @subheading Keybindings
3101 This module also adds key bindings that you can use when looking at a
3102 Planner page to easily jump between the different time-period views.
3107 Move to the view corresponding to the time period one step larger than
3108 the current one. For example, it moves from the weekly view to the
3109 monthly view. It calls @code{planner-zoom-iup}.
3112 Move to the view corresponding to the time period one step smaller
3113 than the current one. For example, it moves from the weekly view to
3114 the daily view. It calls @code{planner-zoom-idown}.
3117 Stay in the same time-period view as the current one, but move one
3118 interval earlier. For example, it moves from @file{2006.January.Week3}
3119 to @file{2006.January.Week2}. It calls @code{planner-zoom-iprev}.
3122 Stay in the same time-period view as the current one, but move one
3123 interval later. For example, it moves from @file{2006.January.Week3}
3124 to @file{2006.January.Week4}. It calls @code{planner-zoom-inext}.
3128 @subheading Example usage
3130 Look at the page named @file{2006.January} and then hit @kbd{S-down}
3131 which will show @file{2006.January.Week1}. Then hit @kbd{S-left} and
3132 @kbd{S-right} to look at @file{2006.January.Week2},
3133 @file{2006.January.Week3}, etc.
3135 @subheading Advanced tips and options
3137 You can use any prefix argument with @code{planner-zoom-iup} and
3138 @code{planner-zoom-idown} to have the new view display in a window
3139 other than the current one. This also works with a nonnumeric prefix
3140 argument and @code{planner-zoom-inext} or @code{planner-zoom-iprev}.
3141 For these two functions, a numeric prefix will specify the number of
3144 If you don't like the default patterns for naming the time-period view
3145 pages, you can change them by customizing @code{planner-zoom-regexps}.
3147 Some people believe weeks start with Sunday, and some believe they
3148 start with Monday. To accommodate both of these colliding worldviews,
3149 @code{planner-zoom-first-day-of-week} can be customized. Its default
3150 value is @samp{1}, which is Monday. If you would prefer Sunday, change
3151 it to @samp{0}. The month to which a week belongs is the month in
3152 which the first day of the week falls.
3154 @subheading Command reference
3156 @defun planner-zoom-iup name other-window
3157 Move to the next higher level in the hierarchy. With a prefix
3158 argument, show the desired page in the other window.
3161 @defun planner-zoom-idown name other-window
3162 Move to the next lower level in the hierarchy. If the current date is
3163 within the higher-level time range, zoom to the lower level time range
3164 that also contains today. Otherwise, just go to the first lower-level
3165 time range. With a prefix argument, show the desired page in the other
3169 @defun panner-zoom-inext name num other-window
3170 Move to the next time range at the same level in the hierarchy. With a
3171 numeric prefix argument, move by that number of time ranges. With a
3172 non-numeric prefix argument, show the desired page in the other window.
3175 @defun planner-zoom-iprev name num other-window
3176 Move to the previous time range at the same level in the hierarchy.
3177 With a numeric prefix argument, move by that number of time ranges.
3178 With a non-numeric prefix argument, show the desired page in the other
3182 @node More about Notes, Making Files Pretty, More about Tasks, More about Planner
3183 @section More about Notes
3184 @cindex notes, more about
3186 Planner by default organizes the notes on a planner page so that
3187 the most recent note is first. Each note is numbered, with the oldest
3188 note labeled @samp{.#1}. If you would like to reverse this behavior,
3189 look at @kbd{C-h v planner-reverse-chronological-notes}.
3191 Notes are associated with day pages, but can also be associated with
3192 plan pages when they are created. A linked note looks like this:
3195 .#1 Headline (LinkedNote#1)
3199 You can jump to the linked note with
3200 @command{planner-jump-to-linked-note}.
3202 Deleting a note can be dangerous, as the notes are automatically
3203 numbered. Removing a note could break links in other pages.
3205 @subheading Functions
3207 @defun planner-create-note page
3208 Create a note to be remembered in @var{page} (today if @var{page} is
3209 nil). If @code{planner-reverse-chronological-notes} is non-nil, create
3210 the note at the beginning of the notes section; otherwise, add it to
3211 the end. Position point after the anchor.
3214 @defun planner-create-note-from-task
3215 Create a note based on the current task and update the current task to
3219 @defun planner-renumber-notes
3220 Update note numbering.
3223 @defun planner-jump-to-linked-note note-info
3224 Display the note linked to by the current note or @var{note-info} if
3228 @defun planner-search-notes regexp limit
3229 Return a buffer with all the notes returned by the query for
3230 @var{regexp}. If called with a prefix argument, prompt for
3231 @var{limit} and search days on or after @var{limit}.
3234 The following sections include instructions for displaying,
3235 manipulating, and navigating your notes efficiently.
3238 * Using Allout Mode:: Quickly navigating your notes
3239 * <notes>:: Note headlines
3240 * <past-notes>:: Index of past notes
3241 * Note Indices:: planner-notes-index.el
3244 @node Using Allout Mode, <notes>, More about Notes, More about Notes
3245 @subsection Using Allout Mode
3247 @cindex notes, navigating
3248 @cindex notes, formatting
3249 @cindex notes, displaying
3251 The format of the notes in Planner works well with Allout mode, which
3252 provides helpful commands for navigating and formatting outlines. You
3253 can, for example, hide the bodies of all the notes on a page so you can
3254 see just their headlines. You can also jump easily from headline to
3255 headline, skipping over the bodies in between.
3257 The commands for using Allout mode vary depending on which Emacs version
3258 you are using. In either case, type @kbd{M-x load-library @key{RET}
3259 allout @key{RET}} to start. If you are using CVS Emacs, type @kbd{M-x
3260 allout-mode @key{RET}}. If you are using an earlier version of Emacs,
3261 type @kbd{M-x outline-mode @key{RET}}.
3263 The exact commands then available to you differ depending on your Emacs
3264 version, but you can view the commands and their keybindings by typing
3265 @kbd{C-h m}. In CVS Emacs, they will start with @command{allout-}, while
3266 in previous versions, they will start with @command{outline-}.
3268 @node <notes>, <past-notes>, Using Allout Mode, More about Notes
3271 @samp{<notes>} is replaced by a list of note headlines when the page
3272 is published. For example, the notes tag in the following example will
3273 be replaced by the two headlines when published. (@pxref{Publishing})
3280 .#1 This is a headline
3282 and this is body text
3284 .#2 This is another headline
3286 and this is more body text
3289 @samp{<notes>} is useful if you want to provide a quick summary of
3290 blog entries at the top of your page. Just add it to your
3291 @code{planner-day-page-template}.
3293 @node <past-notes>, Note Indices, <notes>, More about Notes
3294 @subsection <past-notes>
3296 @samp{<past-notes>} is replaced by an index of note headlines.
3297 If @var{start} is specified, it lists notes starting from that date.
3298 If @var{directory} is specified, you can index notes in another
3302 All the notes I've taken in 2004:
3304 <past-notes start="2004.01.01" end="2004.12.31">
3307 @node Note Indices, , <past-notes>, More about Notes
3308 @comment node-name, next, previous, up
3309 @subsection Note Indices
3310 @cindex @file{planner-notes-index.el}, using
3311 @cindex notes, indexing
3313 Make sure that @file{planner-notes-index.el} is in your load path and
3314 add this to your @file{.emacs} (or @file{_emacs}):
3317 (require 'planner-notes-index)
3320 Then you can use tags of the form:
3323 <planner-notes-index page="2004.03.02">
3324 <planner-notes-index from="2004.03.01" to="2004.03.31">
3325 <planner-notes-index limit="10">
3326 <planner-notes-index page="PlanPage">
3327 <planner-notes-index-month-table month="2004.03" limit="5">
3328 <planner-notes-index-month-table month="2004.03">
3331 You can also use the following interactive functions:
3333 @code{planner-notes-index}
3334 @code{planner-notes-index-days}
3335 @code{planner-notes-index-weeks}
3336 @code{planner-notes-index-months}
3337 @code{planner-notes-index-years} (wow!)
3339 These work based on the current date (date of current buffer, or today).
3341 If a single page is specified, this page is scanned for headlines
3348 The results are presented as a bulleted list.
3350 If @var{from} and @var{to} are specified, all date pages between them
3351 (inclusive) are scanned. If @var{from} is omitted, it is assumed to be
3352 the earliest entry. If @var{to} is omitted, it is assumed to be the
3355 If @var{recent} is specified, the list includes only that many recent
3356 headlines. and the results are presented as a bulleted list.
3358 To customize presentation, you can write a function that generates
3359 the appropriate @code{<planner-notes-index>} tags. You can also use
3360 @code{planner-extract-note-headlines} in your own functions.
3362 @subheading Functions
3364 The following interactive functions are defined in
3365 @file{planner-notes-index.el}:
3367 @defun planner-notes-index &optional from to limit
3368 Display a clickable notes index. If called from a Lisp program,
3369 display only dates between @var{from} and @var{to}. With a prefix arg
3370 @var{limit}, display only that number of entries.
3373 @defun planner-notes-index-days days
3374 Display an index of notes posted over the past few @var{days}. The
3375 list ends with the day of the current buffer or @code{planner-today}.
3378 @defun planner-notes-index-weeks weeks
3379 Display an index of notes posted over the past few @var{weeks}. The
3380 list ends with the week of the current buffer or
3381 @code{planner-today}. Weeks start from Sunday.
3384 @defun planner-notes-index-months months
3385 Display an index of notes posted over the past few @var{months}. The
3386 list ends with the month of the current buffer or @code{planner-today}.
3389 @defun planner-notes-index-years years
3390 Display an index of notes posted over the past few @var{years}. The
3391 current year is included.
3394 @file{planner-notes-index.el} does not define any keybindings.
3397 @node Making Files Pretty, Annotations, More about Notes, More about Planner
3398 @section Making Files Pretty
3400 By default, planner does a little bit of fancy reformatting when you
3401 save a file. Tasks are sorted by priority (ABC) and status (_oP>XC) on
3402 day pages. On plan pages, tasks are sorted by priority (ABC), status
3403 (XC), and date. Undated tasks are sorted after dated tasks.
3407 @defopt planner-sort-tasks-key-function
3408 Control task sorting. Some options include
3409 @code{planner-sort-tasks-default-key},
3410 @code{planner-sort-tasks-basic}, @code{planner-sort-tasks-by-date}, and
3411 @code{planner-sort-tasks-by-link}.
3414 @defopt planner-sort-undated-tasks-equivalent
3415 This option controls the behavior of task sorting on plan pages. By
3416 default, the value @samp{9999.99.99} causes dated tasks to be listed
3417 before undated tasks. To sort undated tasks before dated tasks,
3418 set this to a blank string.
3421 @defopt planner-sort-tasks-automatically
3422 Non-nil means sort tasks whenever a planner file is saved. On day
3423 pages, tasks are sorted by status. On plan pages, they are sorted by
3424 status and date. Sorting can take a while.
3427 @defopt planner-renumber-tasks-automatically
3428 Non-nil means renumber tasks from 1 to N whenever a planner file is
3429 saved. This allows you to refer to tasks in previous day pages using
3430 anchors like @samp{2003.08.12#A1}. If you use this function, make sure
3431 @code{planner-use-task-numbers} is non-nil so that new tasks are created
3435 @defopt planner-align-tasks-automatically
3436 Non-nil means align tasks whenever a planner file is saved. This
3437 causes the status to line up in a neat column if you have less than
3441 @defopt planner-renumber-notes-automatically
3442 Non-nil means renumber the notes. If most of your notes are only on
3443 one page, you might like seeing the notes renumbered if you delete a
3444 note in the middle. However, if you use a lot of cross-referencing,
3445 note renumbering will break those links.
3448 @subheading Functions
3450 @defun planner-sort-tasks
3451 Sort tasks according to planner-sort-tasks-key-function. By default,
3452 sort tasks according to priority and position on day pages, and
3453 according to status, priority, date, and position on plan pages.
3456 @defun planner-renumber-tasks
3457 Update task numbering.
3460 @defun planner-align-tasks
3461 Align tasks neatly. You can add this to @code{write-file-functions} to
3462 have the tasks automatically lined up whenever you save. For best
3463 results, ensure @code{planner-align-tasks} is run after
3464 @code{planner-renumber-tasks}.
3467 @defun planner-fix-tasks
3468 Sort, renumber and align tasks.
3471 @node Annotations, Interactive Lisp, Making Files Pretty, More about Planner
3472 @comment node-name, next, previous, up
3473 @section Annotations
3475 The context included when you create a task and the context included
3476 when you create a note are gained the same way. It sounds like black
3477 magic, but it turns out not to be.
3479 All that happens is, Planner has a list of functions,
3480 @code{planner-annotation-functions}. When you create a task from a
3481 buffer, or remember a note from a buffer, Planner goes through
3482 this list from top to bottom. The first one that returns true is the
3485 For example, if you're in Wanderlust, and you hit the key you've bound
3486 to @code{planner-create-task-from-buffer}, it looks at this list and
3487 does something like this. Is it an ERC buffer? No. Is it a BBDB
3488 buffer? No. Are we in w3m? No. Are we in Wanderlust? Yes. So this
3489 function succeeds. It stops searching and runs the annotation function
3490 for Wanderlust, which in this case finds out who the message is from
3491 and what the message ID of the message is. It then takes those and
3492 constructs a link back to that message, with a link title something
3493 like @samp{Email from Joe Blogs}.
3495 So, you've read the email from Joe Blogs. He's asked you to do
3496 something and you've hit your key to add that task to your list of
3497 things to do. So what you end up with is a description of the task,
3498 and a link back to what made you create the task in the first place.
3500 The same happens with remembering notes, except that it ends up in the
3501 @samp{* Notes} section of your page instead.
3505 To change the behavior of annotations, customize the following options:
3507 @defopt planner-annotation-functions
3508 A list of functions tried in order by
3509 @command{planner-create-task-from-buffer} and other functions that
3510 pick up context. The first non-nil value returned is used as the
3511 annotation. To cause an item to @strong{not} be annotated, return the
3512 empty string @samp{""}.
3515 @defopt planner-annotation-strip-directory
3516 File links are usually generated with the full path to the file so
3517 that you can easily tell apart files with the same base name. If
3518 @code{planner-annotation-strip-directory} is non-nil, though, only the
3519 base name of the file will be displayed. For example, a link to
3520 @samp{/foo/bar/baz} will be displayed as @samp{baz} and hyperlinked to
3524 @defopt planner-annotation-use-relative-file
3525 If t, always use relative filenames.
3526 @code{planner-annotation-use-relative-file} can also be a function that
3527 takes the filename and returns non-nil if the link should be relative.
3528 Filenames are resolved relative to the first directory of your Planner
3529 project in @code{muse-project-alist}. That is, the created link will be
3530 of the form @samp{../../somefile} instead of
3531 @samp{/absolute/path/to/file}. This can be helpful if you publish your
3532 planner files to the Net and your directory structure ensures that
3533 relative links resolve the same from your Plan pages and their
3534 respective publishing directory.
3537 @node Interactive Lisp, Publishing, Annotations, More about Planner
3538 @comment node-name, next, previous, up
3539 @section Interactive Lisp with planner-lisp.el
3540 @cindex Lisp functions, using with Planner
3541 @cindex interactive Lisp fuctions, using with Planner
3542 @cindex @file{planner-lisp.el}, using
3544 You can include interactive Lisp functions in your planner pages.
3546 First, you need @file{planner-lisp.el}. Put this in your @file{.emacs}
3550 (require 'planner-lisp)
3553 Then, add a link to the Lisp function to your page, like:
3557 [[lisp:/plan][Plan]]
3561 This will be rendered as @samp{Plan}. Selecting the link will run the
3562 @code{plan} function interactively.
3564 You can also execute other Lisp expressions. For example:
3567 [[lisp:/(planner-goto (planner-expand-name "+7"))][Next week]]
3570 @file{planner-lisp.el} does not provide any interactive functions or
3573 @node Publishing, Experimental Functions, Interactive Lisp, More about Planner
3577 You can publish your planner files to a variety of different formats.
3578 For example, you can publish your planner in HTML and put it on a
3579 normal web server. No special server support is required. This gives
3580 you an easy way to keep other people up to date on your tasks, keep a
3581 web log, or simply organize information.
3583 Published files are stored in the path specified by
3584 @code{muse-project-alist} for your Planner project. Just copy the
3585 contents of this directory to your web server, and you're all set! Of
3586 course, publishing is completely optional.
3588 Here are some more features related to publishing:
3591 * Publishing Planner pages:: planner-publish.el
3592 * Publishing Calendars:: planner-calendar.el
3593 * Authz Access Restriction:: planner-authz.el
3594 * RSS Publication:: Sharing notes with planner-rss.el
3595 * iCal Task Publication:: Sharing tasks with planner-ical.el
3596 * RDF Publication:: planner-rdf.el
3599 @node Publishing Planner pages, Publishing Calendars, Publishing, Publishing
3600 @comment node-name, next, previous, up
3601 @subsection Publishing Planner pages
3603 @cindex @file{planner-publish.el}, using
3605 Publishing works by providing Muse with the settings and environment for
3608 First, make sure that you have set up a proper
3609 @code{muse-project-alist} (@pxref{Creating Your Planner}).
3614 (require 'planner-publish)
3617 to your @file{.emacs} (or @file{_emacs}).
3619 To publish your entire Planner project, hit @kbd{C-c C-p}
3620 (@code{muse-project-publish}). To publish just the current buffer, hit
3621 @kbd{C-c C-t} (@code{muse-publish-this-file}).
3623 To automatically publish files when you save them, add the following
3624 code to your @file{~/.emacs} (or @file{_emacs}):
3627 (eval-after-load "muse-mode"
3628 (add-hook 'after-save-hook
3630 (when (planner-derived-mode-p 'muse-mode)
3631 (muse-project-publish nil)))
3635 @subheading Styles provided
3637 The following publishing styles are available.
3641 @cindex publishing styles, planner-html
3643 Publish Planner pages to HTML.
3645 @cindex publishing styles, planner-xhtml
3647 Publish Planner pages to XHTML.
3649 @cindex publishing styles, planner-xml
3651 Publish Planner pages to XML.
3655 @subheading Options provided
3657 The following options may be customized to enhance your publishing
3662 @item planner-publish-markup-regexps
3663 List of markup rules for publishing Planner pages.
3665 @item planner-publish-markup-functions
3666 Specify which function to use for publishing different kinds of markup.
3668 @item planner-publish-markup-tags
3669 A list of custom HTML-like tags to recognize when publishing.
3671 @item planner-xml-markup-strings
3672 Strings that are inserted to publish XML markup.
3674 @item planner-xml-header
3675 Header used when publishing Planner XML files.
3676 This may be text or a filename.
3678 @item planner-xml-footer
3679 Footer used when publishing Planner XML files.
3680 This may be text or a filename.
3682 @item planner-html-markup-strings
3683 Strings that are inserted to publish HTML markup.
3685 @item planner-html-style-sheet
3686 CSS stylesheet elements used in Planner HTML and XHTML files.
3687 This can also be one or more @samp{<link>} tags.
3689 @item planner-html-header
3690 Header used when publishing Planner HTML files.
3691 This may be text or a filename.
3693 @item planner-html-footer
3694 Footer used when publishing Planner HTML files.
3695 This may be text or a filename.
3697 @item planner-xhtml-header
3698 Header used when publishing Planner XHTML files.
3699 This may be text or a filename.
3701 @item planner-xhtml-footer
3702 Footer used when publishing Planner XHTML files.
3703 This may be text or a filename.
3705 @item planner-html-inner-header
3706 Extra header section that can be embedded within
3707 @code{planner-html-header} and @code{planner-xhtml-header}.
3709 @item planner-html-inner-footer
3710 Extra header section that can be embedded within
3711 @code{planner-html-footer} and @code{planner-xhtml-footer}.
3713 @item planner-publish-prepare-regexps
3714 List of markup rules to apply before publishing a page with Planner.
3716 @item planner-publish-finalize-regexps
3717 List of markup rules to apply after publishing a page with Planner.
3721 @node Publishing Calendars, Authz Access Restriction, Publishing Planner pages, Publishing
3722 @comment node-name, next, previous, up
3723 @subsection Publishing Calendars
3724 @cindex calendar, publishing
3725 @cindex @file{planner-calendar.el}, using
3727 To publish calendars in your day pages, it is necessary to do two steps.
3730 @item Add @code{(require 'planner-calendar)} to your configuration.
3731 @item Add a @samp{<calendar>} tag to either your header, footer, or
3732 @var{planner-day-page-template}, depending on where you want it to
3736 To display a calendar based on a different day (given here as DAYPAGE),
3737 use @code{<calendar page="DAYPAGE">}.
3739 To get arrows to previous and next months to show up, use
3740 @code{<calendar arrows="t">}. The text in
3741 @var{planner-calendar-prev-month-button} and
3742 @var{planner-calendar-next-month-button} will be used for the arrows to
3743 the previous and next months, respectively.
3745 By default, Muse will not display the arrows properly, due to
3746 limitations in the special-escaping algorithm. To work around this,
3747 remove the @samp{&} rule from @var{muse-xml-markup-specials}, or from
3748 @var{muse-html-markup-specials} if you are using the 3.02.6 version of
3751 It is also possible to create a symlink from the current day page to the
3752 page name specified by @var{planner-calendar-today-page-name}. To
3753 accomplish this, add the following to your configuration.
3756 (eval-after-load "muse-publish"
3757 '(add-hook 'muse-after-publish-hook
3758 'planner-calendar-create-today-link))
3763 @defopt planner-calendar-prev-month-button
3764 HTML text used for previous month buttons.
3767 @defopt planner-calendar-next-month-button
3768 HTML text used for next month buttons.
3771 @defopt planner-calendar-day-header-chars
3772 Number of characters to use for day column header names.
3775 @defopt planner-calendar-today-page-name
3776 Default name for published today page link.
3779 @subheading Functions
3781 @defun planner-calendar-create-today-link
3782 Add this function to @code{muse-after-publish-hook} to
3783 create a ``today'' soft-link to the newest published planner day page,
3784 on operating systems that support POSIX @command{ln}.
3787 @node Authz Access Restriction, RSS Publication, Publishing Calendars, Publishing
3788 @comment node-name, next, previous, up
3789 @subsection Authz Access Restriction
3790 @cindex @file{planner-authz.el}, using
3791 @cindex Mason, restricting portions with
3792 @cindex access, restricting
3794 @file{planner-authz.el} was written by Andrew J. Korty in order to
3795 allow the easy restriction of portions of published pages. It uses
3796 the HTML::Mason module available on CPAN
3797 (@url{http://www.cpan.org}). Setting up HTML::Mason is
3798 outside the scope of this document. Make sure that it works before
3799 trying out @file{planner-authz.el}.
3801 @file{planner-authz.el} modifies the behavior of
3802 @command{muse-project-publish} so that published pages follow access
3805 This library lets you publish your planner pages while controlling
3806 access to certain portions of them to users you specify. When you
3807 load this library, you gain access to two additional markup directives
3808 to use in your planner pages. The @samp{<authz>} tag lets you
3809 restrict access to arbitrary content as follows:
3812 Here is a sentence everyone should see. This sentence also
3813 contains no sensitive data whatsoever. <authz users="ajk">This
3814 sentence, however, talks about my predilection for that French
3815 vanilla instant coffee that comes in the little tin, and I'm
3816 embarrassed for anyone else to know about that.</authz> And
3817 here's some more perfectly innocuous content.
3820 You can use @samp{<authz>} tags to mark up entire paragraphs, tasks,
3821 notes, and anything else. The tags are replaced with Mason code in
3822 the published pages.
3824 The @samp{#authz} directive restricts access to an entire page. A Mason
3825 call is added to this page to generate a 403 error when someone not
3826 listed tries to access it. Any notes or tasks on a
3827 @samp{#authz}-protected page are also wrapped in Mason code on linked
3828 pages. To add a @samp{#authz} directive to a Muse page, place
3829 @samp{#authz} followed by a space-delimited list of users on one
3836 @subheading Getting started
3838 Add the following to your .emacs file to cause @kbd{M-x
3839 muse-project-publish} to automatically use planner-authz features.
3842 (require 'planner-authz)
3845 @subheading Diary markup
3847 If your pages have a section with diary entries maintained by
3848 planner-appt.el (or by any other means), you can control access to these
3849 entries. First, customize @code{planner-section-tagnames} to map your
3850 diary section ("* Schedule", in this example) to a tag called
3851 "diary-section". An example follows.
3854 (add-to-list 'planner-section-tagnames '("Schedule" . "diary-section"))
3857 If the name of your diary section is "* Diary", you will not need to
3858 customize @code{planner-section-tagnames} by default.
3860 Then make sure the diary entries you want restricted contain a
3861 corresponding plan page name in parentheses, as in the following
3865 10:00 10:30 Meeting with boss (WorkStuff)
3870 @defopt planner-authz-project-default
3871 Default access list for project pages (not day pages). If a given
3872 project page doesn't contain a @samp{#authz} tag, it will receive the
3873 access list defined here. If this variable is nil, all users will be
3874 allowed to view the page. No corresponding variable is provided for
3875 day pages because it doesn't seem like you'd ever want to control
3876 access based on what day it was. (But I will accept patches. :) Notes
3877 and tasks referencing pages without @samp{#authz} tags will also be
3878 restricted to the users listed here.
3881 @defopt planner-authz-day-note-default
3882 Default access list for notes on day pages not associated with
3883 any project. There is way to set a default for notes on project
3884 pages for the reason above; they would only be associated with
3888 @defopt planner-authz-day-task-default
3889 Same as @kbd{planner-authz-day-note-default}, but for tasks.
3892 @subheading Functions
3894 @defun planner-authz-publish-index
3895 Publish an index for the planner marked up with Mason code.
3896 Only those links to pages which the remote user is authorized to
3897 access will be shown.
3900 @node RSS Publication, iCal Task Publication, Authz Access Restriction, Publishing
3901 @comment node-name, next, previous, up
3902 @subsection RSS Publication
3903 @cindex @file{planner-rss.el}, using
3907 @file{planner-rss.el} allows you to publish your notes in the RSS 2.0
3908 XML format for blog syndication. You will also want to customize the
3909 following variables:
3911 To manually add the current note to all the matching RSS feeds, invoke
3912 @command{planner-rss-add-note}. You can specify a filename with the
3913 universal prefix, like this: @kbd{C-u M-x planner-rss-add-note}.
3915 If you use the @file{remember-planner.el} module to create notes, you
3916 can automatically publish new notes to RSS feeds by adding the
3917 following code to your @file{.emacs} (or @file{_emacs}).
3920 (add-to-list 'remember-planner-append-hook 'planner-rss-add-note t)
3925 @defopt planner-rss-base-url
3926 Base absolute URL for published blog entries. Should include trailing
3930 @defopt planner-rss-category-feeds
3931 Rules for automatic categorization of posts and publishing to RSS
3932 files. A blog entry is matched against each condition. If it matches
3933 the regular expression or the function returns a non-nil value, the
3934 blog entry is copied into the specified file.
3937 @defopt planner-rss-feed-limits
3938 A list of regular expressions that match feed filenames and the size
3939 and item limits for feeds that match. For example, you can use
3940 @samp{(("." nil 10))} to ensure that all feeds are limited to the 10
3944 @subheading Functions
3946 @file{planner-rss.el} defines the following interactive functions:
3948 @defun planner-rss-add-note @var{feed}
3949 Export the current note using @code{planner-add-item}. If @var{feed}
3950 is specified, add the entry to the specified file. Else, add the entry
3951 to all matching RSS feeds specified by
3952 @code{planner-rss-category-feeds}.
3955 @node iCal Task Publication, RDF Publication, RSS Publication, Publishing
3956 @comment node-name, next, previous, up
3957 @cindex @file{planner-ical.el}, using
3958 @subsection iCal Publication
3960 iCal is an Internet Engineering Task Force (IETF) standard for
3961 calendaring and scheduling. @uref{http://www.ietf.org/rfc/rfc2445.txt}
3963 You can export your tasks to the iCal format using
3964 @file{planner-ical}. Add @code{(require 'planner-ical)} to your
3965 @file{~/.emacs}. Then you can use @kbd{M-x planner-ical-export-page}
3966 to display the iCal equivalent of tasks on a page, which you can then
3969 To export today's tasks to a file in your publishing directory, add
3970 the following to your @file{~/.emacs}.
3973 (planner-ical-export-file
3977 (muse-style-element :path (car (cddr (muse-project planner-project))))))
3980 @subheading Functions
3982 @defun planner-ical-export-page page &optional file
3983 Export PAGE's tasks in the iCal format.
3984 If FILE is non-nil, results are saved to that file.
3985 If FILE is nil, results are displayed in a `planner-ical-export-buffer'.
3988 @defun planner-ical-export-this-page
3989 Display the tasks on the current page in iCal format.
3992 @node RDF Publication, , iCal Task Publication, Publishing
3993 @comment node-name, next, previous, up
3994 @subsection RDF Publication
3995 @cindex @file{planner-rdf.el}, using
3996 @cindex RDF, publishing to
3998 Put planner-rdf.el in a directory that is in your Emacs load-path and
3999 the following into your ~/.emacs file:
4002 (require 'planner-rdf)
4003 (eval-after-load "muse-publish"
4005 (add-hook 'muse-after-publish-hook
4006 'planner-rdf-publish-file)
4007 (add-hook 'muse-after-publish-hook
4008 'planner-rdf-publish-index)))
4012 * Publishing with planner-rdf::
4013 * planner-rdf Tags::
4014 * planner-rdf Usage Examples::
4017 @node Publishing with planner-rdf, planner-rdf Tags, RDF Publication, RDF Publication
4018 @subsubsection Publishing with planner-rdf
4020 Planner-rdf is now included in the normal Planner publishing process.
4021 Pressing @key{C-p} will create a .owl and a .rdf file for every planner
4022 file. Additionally it creates an index, @file{index.rdf}.
4024 By default all generated files will be stored in the normal Planner
4025 publishing directory, where the HTML files end up. If you would ike to
4026 change that, set the variable @code{planner-rdf-directory} to the desired
4029 The generated files:
4033 @file{index.rdf} - a collection with pointers to the
4034 @file{<plan-page>.rdf} files.
4036 @file{<plan-page>.rdf} - contains Dublin Core metadata about the files
4037 related to the current Planner page. Currently it contains metadata
4038 about the source file, the Emacs plan page, the generated HTML page, and
4039 the generated OWL file.
4041 @file{<plan-page>.owl} - contains task and note data from the Planner
4042 file. Task information is stored completely. For notes, the note
4046 @node planner-rdf Tags, planner-rdf Usage Examples, Publishing with planner-rdf, RDF Publication
4047 @subsubsection planner-rdf Tags
4049 Besides the factual information, e.g. the task status or description,
4050 planner-rdf extracts links (in the format @samp{[[...][...]]} or
4051 @samp{[[...]]}) and tags (@samp{@{@{...:...}@}@}) from tasks and notes
4052 (including the notes text). Links and tags provide context for the plan
4053 elements and so are stored and linked with the containing elements.
4055 Links point to locations that can be used to enrich the information in
4056 the Planner pages (e.g, by retrieving data from them and adding it),
4057 tags -- like the one for the task ids @samp{@{@{Tasks:198@}@}} -- can be
4058 used to express abstract qualities. Some examples:
4062 an @samp{@{@{audience:myteam@}@}} tag, can be used to restrict
4063 publishing of items to a certain user group;
4064 @item a @samp{@{@{lang:de@}@}} tag, signifying the language of the text;
4066 a @samp{@{@{location:Hamburg@}@}} tag, can be used to make geographic
4067 reference to an entity that is not stored in your address book, bbdb.
4070 What tags to use is up to the user. Planner-rdf makes no assumptions
4071 about them, it just extracts and stores them. Only the applications
4072 using the data know what to do with them.
4074 @node planner-rdf Usage Examples, , planner-rdf Tags, RDF Publication
4075 @subsubsection Usage Examples
4077 Report generation with OpenOffice
4079 The Perl file @file{this-week.pl}
4080 (@url{http://www.rainervolz.de/planner-rdf/this-week.pl}) creates a
4081 simple report for the current week. The script extracts task and note
4082 information from the generated OWL files and inserts it into a simple
4083 OpenOffice Writer document. Nothing fancy, just a proof of concept, to
4084 show how planner-rdf can be used to integrate Planner Mode with other
4087 Besides Perl and OpenOffice you'll need the Redland RDF Application
4088 Framework (@url{http://www.redland.opensource.ac.uk/}). It is used to
4089 process the RDF data. Redland is small, but powerful, and available
4090 for many platforms and languages.
4092 As an example the application loads the RDF data each time it is run.
4093 In the real world you probably would use Redland to store the Planner
4094 data in a database, to save the loading step each time you access the
4097 Importing Planner data into Protege
4099 Protege is a popular ontology editor and knowledge management
4100 application. A simple way to import data into it, is to provide a OWL
4101 file that contains the data as well as the schema. To do this:
4105 Use @file{planner2protege.pl}
4106 (@url{http://www.rainervolz.de/planner-rdf/planner2protege.pl}) to
4107 combine all OWL files into a single one.
4109 Use CWM (@url{http://www.w3.org/2000/10/swap/doc/cwm.html}) to combine
4110 schema and data, with @code{python cmw --rdf planner-rdf.owl
4111 planner-data.owl --think --rdf >planner2.owl}
4114 Not the most straightforward process, but it works. The resulting file,
4115 here planner2.owl, can then be loaded into Protege.
4117 @node Experimental Functions, , Publishing, More about Planner
4118 @comment node-name, next, previous, up
4119 @section Experimental Functions
4120 @cindex @file{planner-experimental.el}, using
4121 @cindex experimental functions, Planner
4123 These functions are experimental. This means that they may not do
4124 exactly what you expect them to do, so keep backups, be careful, and
4127 To use these functions, make sure that @file{planner-experimental.el} is
4128 in your load path, and add this to your @file{.emacs} (or
4132 (require 'planner-experimental)
4135 @subheading Functions
4137 @file{planner-experimental.el} defines the following interactive
4140 @defun planner-search-notes-next-match
4141 Jump to the next matching entry. Call after
4142 @code{planner-search-notes}.
4145 @defun planner-search-notes-previous-match
4146 Jump to the previous matching entry. Call after
4147 @code{planner-search-notes}.
4150 @defun planner-remove-duplicates
4151 Remove duplicate tasks.
4154 @file{planner-experimental.el} does not define any keybindings.
4156 @node Managing Your Information, Advanced Configuration, More about Planner, Top
4157 @comment node-name, next, previous, up
4158 @chapter Managing Your Information
4160 Planner can be integrated with other Emacs and even some non-Emacs
4161 programs by loading additional modules. You can pick and choose from
4162 these modules, choosing those that work with programs you use and that
4163 produce information you want to have included in your Planner pages.
4166 * E-mail:: Linking notes and tasks to messages
4167 * Scheduling and Time:: Tracking appointments and where your time goes
4168 * Finances:: Display your account balances and more
4169 * Contacts and Conversations:: BBDB and ERC
4170 * Tracking Research and Resources:: The Web, bibliographies, and bookmarks
4171 * Tracking Development::
4174 @node E-mail, Scheduling and Time, Managing Your Information, Managing Your Information
4175 @comment node-name, next, previous, up
4178 Planner can work together with several different Emacs e-mail
4179 clients. If you load the appropriate module for the e-mail client you
4180 use, then your notes and tasks can be annotated with information
4181 pointing to the specific e-mail message you were reading when you
4182 created that note or task. When you are looking at the note or task, you
4183 will be able to jump straight to that message.
4186 * Unix mail:: Unix mailboxes: planner-unix-mail.el
4187 * Gnus:: Gnus mail and news reader: planner-gnus.el
4188 * VM:: VM mail reader: planner-vm.el
4189 * Wanderlust:: Wanderlust mail reader: planner-wl.el
4190 * MH-E:: MH-E mail reader: planner-mhe.el
4191 * Rmail:: Rmail: planner-rmail.el
4195 @node Unix mail, Gnus, E-mail, E-mail
4196 @comment node-name, next, previous, up
4197 @subsection Unix mail
4198 @cindex @file{planner-unix-mail.el}, using
4199 @cindex mbox, using Planner with
4200 @cindex Unix mail, using Planner with
4201 @cindex mail client, using Planner with
4203 This module supports links from any kind of Unix mailbox (mbox). To
4204 use this module, make sure that @file{planner-unix-mail.el} is in your
4205 load path and add this to your @file{.emacs} (or @file{_emacs}):
4208 (require 'planner-unix-mail)
4211 Unix mail URLs are of the form:
4214 ;; mail://PATH/TO/INBOX/message-id
4217 Annotations will be of the form:
4220 [[mail://PATH/TO/INBOX/E1AyTpt-0000JR-LU%40sacha.ateneo.edu][E-mail from Sacha Chua]]
4223 @file{planner-unix-mail.el} does not define any interactive functions or
4224 create any new keybindings.
4226 @node Gnus, VM, Unix mail, E-mail
4227 @comment node-name, next, previous, up
4229 @cindex Gnus, using Planner with
4230 @cindex mail client, using Planner with, Gnus
4231 @cindex @file{planner-gnus.el}, using
4233 To use this module, make sure that it is in your load path and put
4234 this in your @file{.emacs} (or @file{_emacs}):
4237 (require 'planner-gnus)
4238 (planner-gnus-insinuate)
4241 With this module loaded, when you create tasks from Gnus summary or
4242 message buffers, the tasks will be annotated with information from the
4243 message you were looking at when you created each task. A link will also
4244 be created on your planner page that you can select in order to return
4247 So, the created task will look something like this:
4250 #A34 _ Send writing to publishme.com from
4251 [[gnus://alt.books.beatgeneration/<Ifo5c.24632$F9.9567@@nwrddc01.gnilink.net>][E-Mail
4252 from editor@@verizon.net]] @{@{Tasks:71@}@} ([[Writing]])
4255 This module also binds @kbd{C-c C-t} in the Gnus summary and article
4256 views to the command to create a new task.
4258 @file{planner-gnus.el} does not define any interactive functions.
4260 For more information about Gnus, see @inforef{Top, The Gnus Newsreader,
4263 @node VM, Wanderlust, Gnus, E-mail
4264 @comment node-name, next, previous, up
4266 @cindex VM, using Planner with
4267 @cindex mail client, using Planner with, VM
4268 @cindex @file{planner-vm.el}, using
4270 To use this module, make sure that @file{planner-vm.el} is in your load
4271 path and add this to your @file{.emacs} (or @file{_emacs}):
4274 (require 'planner-vm)
4277 VM URLs are of the form:
4280 vm://path/to/inbox/message-id
4283 Annotations will be of the form:
4286 [[vm://home/test/INBOX/<E1AyTpt-0000JR-LU@@sacha.ateneo.edu>][E-mail from Sacha Chua]]
4289 @file{planner-vm.el} does not define any interactive functions or
4293 @node Wanderlust, MH-E, VM, E-mail
4294 @comment node-name, next, previous, up
4295 @subsection Wanderlust
4296 @cindex Wanderlust, using Planner with
4297 @cindex mail client, using Planner with, Wanderlust
4298 @cindex @file{planner-wl.el}, using
4300 To use this module, make sure that @file{planner-wl.el} is in your
4301 load path and add this to your @file{.emacs} (or @file{_emacs}):
4304 (require 'planner-wl)
4307 Then, when you call @kbd{M-x planner-create-task-from-buffer} from
4308 Wanderlust summary or message buffers, the task will be created with
4309 the correct annotation.
4313 To add keybindings to Wanderlust, call:
4316 (planner-wl-insinuate)
4319 This binds @kbd{C-c C-t} to @command{planner-create-task-from-buffer}.
4321 @node MH-E, Rmail, Wanderlust, E-mail
4322 @comment node-name, next, previous, up
4324 @cindex MH-E, using Planner with
4325 @cindex mail client, using Planner with, MH-E
4326 @cindex @file{planner-mhe.el}, using
4328 To use this module, make sure that @file{planner-mhe.el} is in your
4329 load path and add this to your @file{.emacs} (or @file{_emacs}):
4332 (require 'planner-mhe)
4335 Then, when you call @kbd{M-x planner-create-task-from-buffer} from
4336 MH-E summary or message buffers, the task will be created with
4337 the correct annotation.
4339 @file{planner-mhe} does not define any interactive functions.
4341 @node Rmail, , MH-E, E-mail
4342 @comment node-name, next, previous, up
4344 @cindex Rmail, using Planner with
4345 @cindex mail client, using Planner with, Rmail
4346 @cindex @file{planner-rmail.el}, using
4348 To use this module, make sure that @file{planner-rmail.el} is in your
4349 load path and add this to your @file{.emacs} (or @file{_emacs}):
4352 (require 'planner-rmail)
4355 Rmail URLs are of the form:
4361 Annotations will be of the form:
4364 [[rmail://<E1AyTpt-0000JR-LU@@sacha.ateneo.edu>][E-mail from Sacha Chua]]
4367 @file{planner-rmail.el} does not define any interactive functions or
4368 create any new keybindings.
4370 For more information about Rmail, see @inforef{Rmail, Reading Mail With
4373 @node Scheduling and Time, Finances, E-mail, Managing Your Information
4374 @comment node-name, next, previous, up
4375 @section Scheduling and Time
4378 * Diary:: Using the Emacs diary: planner-diary.el
4379 * Appointments:: Appointments in plan pages: planner-appt.el
4380 * Timeclock:: Time tracking: planner-timeclock.el
4381 * schedule.el:: Project completion: planner-schedule.el
4385 @node Diary, Appointments, Scheduling and Time, Scheduling and Time
4386 @comment node-name, next, previous, up
4388 @cindex diary, using Planner with
4389 @cindex @file{planner-diary.el}, using
4391 If you use Emacs's diary feature, Planner-Diary could be helpful for
4392 you. It puts all diary entries for the current day in the @samp{*
4393 Diary} section of your day plan page. This section is updated every
4394 time you display the file in Emacs. By default the diary section of
4395 past pages is not updated; it's pretty unlikely that you want to add
4396 new diary entries for the past. (@pxref{Diary, , , Emacs, GNU Emacs
4399 If you want to use @file{planner-diary.el}, make sure the file is in
4400 your load path and add this to your @file{.emacs} (or @file{_emacs}):
4403 (require 'planner-diary)
4406 @file{planner-diary.el} needs @command{fancy-diary-display}. To use
4407 @command{fancy-diary-display}, add this to your @file{.emacs} (or
4411 (add-hook 'diary-display-hook 'fancy-diary-display)
4414 You can use Planner-Diary in two different ways:
4419 If you want the saved files to contain your entries and not just a line
4420 of Lisp, add the following lines to your @file{.emacs} (or @file{_emacs}):
4423 (setq planner-diary-use-diary t)
4424 (planner-diary-insinuate)
4427 You should also customize or set @code{planner-day-page-template} to
4428 include a @samp{* Diary}:
4431 (setq planner-day-page-template
4432 "* Tasks\n\n\n* Schedule\n\n\n* Diary\n\n\n* Notes")
4435 @kbd{C-c C-e} updates the diary sections. @kbd{C-u C-c C-e} forces an
4436 update---it inserts the diary section for the day, even if the day is in
4437 the past or if there is no @samp{Diary} section in the buffer.
4440 (GNU EMACS ONLY) You can put the following line of Lisp code in your
4441 day plan pages to display your diary entries:
4444 <lisp>(planner-diary-entries-here)</lisp>
4447 You can do this automatically for all day plan pages:
4450 (setq planner-day-page-template
4451 "* Tasks\n\n\n* Diary\n\n<lisp>(planner-diary-entries-here)</lisp>
4455 When you open a day plan page outside Emacs, you will see the line of
4456 Lisp code and not your diary entries.
4460 If you want to see your diary entries for more than just one day, set
4461 @code{planner-diary-number-of-days} accordingly. This works for either
4462 of the two approaches.
4464 These diary sections are only intended for display. Editing them will
4465 not affect your diary file. If you want to add entries to your diary,
4466 you should use the usual Emacs diary and calendar methods for doing
4467 that, or call @code{planner-diary-add-entry}.
4469 If you want to use the Cal-Desk package, simply follow the instructions
4470 in @file{cal-desk.el}. If you get the Cal-Desk layout from the Calendar
4471 buffer, you get it in the day plan buffer, too.
4473 If you use Planner-Diary, you might consider using the Calendar support
4474 of Planner. (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) To get
4475 Calendar integration, add this to your @file{.emacs} (or @file{_emacs}):
4478 (planner-insinuate-calendar)
4481 If @code{planner-diary-create-section-flag} is non-nil, sections are
4482 always inserted if necessary.
4484 @cindex planner2diary.py, using
4485 If you want to import Planner entries into your Diary file, the
4486 @file{planner2diary.py} script will accomplish this for you. To use it,
4487 execute @code{planner2diary.py} on the command line, specifying your
4488 planner directory as the first and only argument.
4492 @defopt planner-diary-create-section-flag
4493 Non-nil means create the requested diary sections if they do not
4494 exist. By default, planner-diary tries to create the section. If you
4495 want more control over your pages, you can set this to nil. Trying to
4496 write a diary section to a page that does not have it yet will then
4500 By default, planner-diary lists only the appointments you have on that
4501 day. If you want the date headers included even when showing the diary
4502 entries for a single day, set planner-diary-include-all-output to
4505 @defopt planner-diary-include-all-output-flag
4506 Non-nil means don't omit any data when copying diary entries into day
4510 @subheading Functions
4512 @file{planner-diary.el} defines the following interactive functions:
4514 @defun planner-diary-add-entry date time text
4515 Prompt for a diary entry to add to @code{diary-file} on @var{date}.
4516 Uses @code{planner-annotation-functions} to make hyperlinks.
4517 @var{time} and @var{text} are used in the description."
4520 @defun planner-diary-insert-diary force
4521 Insert the fancy diary for the day into the day plan file. If
4522 @var{force} is non-nil, insert a diary section even if there is no
4523 @var{planner-diary-string} in the buffer.
4526 @defun planner-diary-insert-diary-maybe force
4527 Maybe insert the fancy diary for the day into the day plan file. If the
4528 current day is in the past and @var{force} is nil, don't do anything. If
4529 @var{force} is non-nil, insert a diary section even if there is no
4530 @code{planner-diary-string} in the buffer.
4533 @defun planner-diary-insert-appts force
4534 Insert the diary appointments for the day into the day plan file. If
4535 @var{force} is non-nil, insert a diary appointments section even if
4536 there is no @code{planner-diary-appts-string} in the buffer.
4539 @defun planner-diary-insert-appts-maybe force
4540 Maybe insert the diary appointments for the day into the day plan file.
4541 If the current day is in the past and @var{force} is nil, don't do
4542 anything. If @var{force} is non-nil, insert a diary appointments
4543 section even if there is no @code{planner-diary-appts-string} in the
4547 @defun planner-diary-insert-cal-desk force
4548 Insert the cal-desk diary for the day into the day plan file. If
4549 @var{force} is non-nil, insert a cal-desk diary section even if there is
4550 no @code{planner-diary-cal-desk-string} in the buffer.
4553 @defun planner-diary-insert-cal-desk-maybe force
4554 Maybe insert the cal-desk diary for the day into the day plan file. If
4555 the current day is in the past and @var{force} is nil, don't do
4556 anything. If @var{force} is non-nil, insert a cal-desk appointments
4557 section even if there is no @code{planner-diary-cal-desk-string} in the
4561 @defun planner-diary-insert-public force
4562 Insert the public diary for the day into the day plan file. If
4563 @var{force} is non-nil, insert a public diary section even if there is
4564 no @code{planner-diary-public-string} in the buffer.
4567 @defun planner-diary-insert-public-maybe force
4568 Maybe insert the public diary for the day into the day plan file. If
4569 the current day is in the past and @var{force} is nil, don't do
4570 anything. If @var{force} is non-nil, insert a public appointments
4571 section even if there is no @code{planner-diary-public-string} in the
4575 @defun planner-diary-insert-private force
4576 Insert the private diary for the day into the day plan file. If
4577 @var{force} is non-nil, insert a private diary section even if there is
4578 no @code{planner-diary-private-string} in the buffer.
4581 @defun planner-diary-insert-private-maybe force
4582 Maybe insert the private diary for the day into the day plan file. If
4583 the current day is in the past and @var{force} is nil, don't do
4584 anything. If @var{force} is non-nil, insert a private appointments
4585 section even if there is no @code{planner-diary-private-string} in the
4589 @defun planner-diary-insert-all-diaries force
4590 Update all diary sections in a day plan file. If @var{force} is
4591 non-nil, insert a diary section even if there is no section header. It
4592 only inserts diaries if the corresponding @code{planner-diary-use-}*
4593 variable is @samp{t}.
4596 @defun planner-diary-insert-all-diaries-maybe force
4597 Update all diary sections in a day plan file. If the current day is in
4598 the past and @var{force} is nil, don't do anything. If @var{force} is
4599 non-nil, insert a diary section even if there is no section header. It
4600 only inserts diaries if the corresponding @code{planner-diary-use-}*
4601 variable is @samp{t}.
4604 @defun planner-diary-show-day-plan-or-diary
4605 Show the day plan or diary entries for the date under point in calendar.
4606 Add this to @code{calendar-move-hook} if you want to use it. In that
4607 case, you should also @command{remove-hook} @samp{planner-calendar-show}
4608 from @code{calendar-move-hook}.
4613 @file{planner-diary.el} adds the following keybinding to Planner, if
4614 @command{planner-diary-insinuate} is in your @file{.emacs} (or
4620 @kbd{C-c C-e} updates the diary sections by calling
4621 @code{planner-diary-insert-all-diaries-maybe}.
4626 * Planner-Diary Advanced Features::
4629 @node Planner-Diary Advanced Features, , Diary, Diary
4630 @comment node-name, next, previous, up
4631 @subsubsection Planner-Diary Advanced Features
4632 @cindex diary, using Planner with
4633 @cindex @file{planner-diary.el}, advanced features
4635 The features described here are part of the development version. They
4636 are subject to change without notice. They may be buggy. The
4637 documentation may be inaccurate. Use at your own risk.
4639 There is a lot of code redundancy in the development version. This is
4640 intentional and makes it easier to change the code for one type of diary
4641 section without breaking others.
4643 @subheading Diary views
4645 @cindex @file{planner-diary.el}, views
4646 Currently Planner-Diary supports six different views of your diary
4651 Ordinary fancy diary display (what you get by pressing @kbd{d} in the
4652 calendar buffer with @code{fancy-diary-display} switched on)
4655 Schedule/Appointments (all entries from 1 that have a time assigned to
4659 Diary without appts (1 without 2)
4662 cal-desk display (appts on top, non appts entries at bottom)
4665 A private diary (same as 1, but uses a different diary-file)
4668 A public diary (same as 1, but uses a different diary-file)
4671 Put the following line of Lisp code in your day plan pages to display
4675 <lisp>(planner-diary-entries-here)</lisp>
4678 The function @code{planner-diary-entries-here} takes two optional
4679 arguments---the diary file you want to use and the number of days you
4682 @subheading Exporting Planner-specific Diary files
4684 @cindex @file{planner-diary.el}, exporting entries
4685 If you would like to export diary entries from your Planner pages to
4686 separate Diary files, add @code{(require 'planner-export-diary)} to your
4687 config. The following steps describe the usage of the functions and
4688 options contained in this file.
4693 Customize @code{planner-export-diary-file}. The default value is
4694 ``~/diary.planner''.
4697 Add the following line to your main Diary file (default: ``~/diary'').
4700 #include ~/diary.planner
4704 Then, call @command{M-x planner-export-diary-future} whenever you want
4705 future diary entries published. You can automatically publish entries by
4706 adding either of the following to your .emacs.
4710 @item (planner-export-diary-future)
4711 Publish future entries on startup.
4713 @item (add-hook 'planner-mode-hook 'planner-export-diary-setup)
4714 Publish future entries whenever you save a Planner file.
4720 @node Appointments, Timeclock, Diary, Scheduling and Time
4721 @comment node-name, next, previous, up
4722 @subsection Appointments
4723 @cindex appointments
4724 @cindex @file{planner-appt.el}, using
4726 If you would like to use planner for your appointment alerts
4727 instead of using the diary system, you might like to try
4728 @file{planner-appt}.
4730 According to your preferences, you may choose from two different
4731 approaches. Appointments in task descriptions on today's plan
4735 #A _ @@12:45 Do something (TaskPool)
4739 and appointments in today's schedule section are like this:
4744 9:00 | 12:00 | Read Simmel's Philosophy of Money
4745 @@12:45 | | Do Something Else
4746 @@13:00 | 14:00 | lunch
4750 You can even use both at the same time if you like.
4752 @c Jim Ottaway <j.ottaway@lse.ac.uk>: Changed these kinds of heading
4753 @c back to @unnumberedsec, but left the originals commented out in
4754 @c case there was a good reason for the @strong formatting.
4758 @unnumberedsubsubsec Usage
4760 In the file where you configure Planner, add one of the following.
4764 For task-based appointments: @code{(planner-appt-use-tasks)}
4766 For schedule-based appointments: @code{(planner-appt-use-schedule)}
4768 For both task- and schedule-based appointments:
4769 @code{(planner-appt-use-tasks-and-schedule)}
4773 And finally if you want everything to be updated automatically add:
4776 (planner-appt-insinuate)
4779 If you don't want to do the insinuation then you can call:
4782 M-x planner-appt-update
4786 after editing appointments on the page (note that this is not
4787 necessary if you use tasks for the appointments and you don't edit
4788 the task descriptions outside of @code{planner-edit-task-description}).
4790 Try both methods; if you find that you prefer one over the
4791 other, use one of the specific @code{planner-appt-use-} functions, as
4792 there are some performance gains when using one method exclusively.
4795 * Task-based Appointments::
4796 * Schedule-based Appointments::
4797 * Viewing Appointments::
4798 * Appointment Updating on Save::
4799 * Appointment and Calendar Integration::
4800 * Appointment Hooks::
4804 @node Task-based Appointments, Schedule-based Appointments, Appointments, Appointments
4805 @comment node-name, next, previous, up
4806 @subsubsection Task-based Appointments
4807 @cindex appointments, task-based
4808 @cindex task-based appointments
4810 A task has an appointment if it looks like this:
4813 #A _ @@12:45 Do something (TaskPool)
4817 i.e., if it has @@ followed by a time at the beginning. This means
4818 the task is a regular appointment, and will not be carried forward
4819 at the start of a new day.
4821 Alternatively, it may have a !, like this:
4824 #A _ !12:45 Do something else (TaskPool)
4828 This makes it a "nagging" appointment, which @emph{will} be carried
4829 forward. It will, however, lose the appointment time in the
4832 This may seem like a strange feature, but here is Henrik's
4836 Sometimes I have a task that I want to do at a certain time, so I
4837 make it an appointment. If I don't get around to doing it anyway,
4838 I want it to be carried forward. Basically, I sometimes use
4839 appointments on tasks to annoy me until I get them done. :)
4842 You can edit, move and delete tasks with the usual functions, and
4843 appointments will be updated automatically.
4845 You can update all task appointments on your page with
4848 M-x planner-appt-update
4852 @c @strong{Cyclic Entries}
4854 @unnumberedsubsubsec Cyclic Entries
4855 @cindex appointments, cyclic task entries
4857 If you have @file{planner-cyclic} (@pxref{Cyclic Tasks}) loaded, entries
4858 in your cyclical tasks file such as
4861 Friday #A _ @@12:45 staff meeting
4865 will appear every Friday and there will be an appointment alert set
4869 @c @strong{Appointments Section}
4870 @unnumberedsubsubsec Appointments Section
4871 @cindex appointments, appointments section
4873 You can have all task-based appointments copied to a separate section,
4874 providing an overview of your appointments.
4879 (setq planner-appt-task-use-appointments-section-flag t)
4882 @noindent to your configuration, or use @kbd{M-x customize-variable}.
4884 The variable @code{planner-appt-task-appointments-section} is the name
4885 of the section where the appointments will be copied. By default, it is
4886 set to @code{"Schedule"}, which means that task appointments will be
4887 intermingled with schedule entries.
4889 It is also a good idea to add the section you wish to use to
4890 @code{planner-day-page-template} in order to control where that section
4891 will appear on the page (otherwise it will appear at the top).
4893 The format of the appointments follows that of a schedule; if you
4894 don't like the way it looks, you can write something different and set
4895 @code{planner-appt-format-appt-section-line-function} appropriately.
4896 See the documentation for
4897 @code{planner-appt-format-appt-section-line-function} for details. It
4898 should be fairly easy to see what needs to be done if you look at the
4899 source for the default function (which is
4900 @code{planner-appt-format-appt-section-line}).
4902 If the section specified in
4903 @code{planner-appt-task-appointments-section} is the same as the
4904 schedule section specified in @code{planner-appt-schedule-section} (by
4905 default @code{"Schedule"}), the default formatting function adds a
4906 @samp{#} to the description so that one can visually distinguish
4907 appointments from the task list from those that have been added to the
4910 @node Schedule-based Appointments, Viewing Appointments, Task-based Appointments, Appointments
4911 @comment node-name, next, previous, up
4912 @subsubsection Schedule-Based Appointments
4913 @cindex appointments, schedule-based
4914 @cindex schedule-based appointments
4916 Some scheduled tasks require reminders, others don't. In this
4922 9:00 | 12:00 | Read Simmel's Philosophy of Money
4923 @@12:45 Do Something Else
4924 @@13:00 | 14:00 | lunch
4925 @@14:30 | | Meet jrs to discuss his dissertation
4926 @@16:00 Test Society seminar
4931 those that have an @@ prefix will be added to the appointment
4932 reminder list; the others will not. The formats that are
4933 recognized are fairly flexible, as you can see from the example.
4935 If you change your schedule, you can update the appointment list
4939 M-x planner-appt-update
4942 @noindent You can also have the schedule sorted as part of the update,
4943 if you have this in your configuration:
4946 (setq planner-appt-sort-schedule-on-update-flag t)
4950 @c @strong{Cyclical Entries}
4951 @unnumberedsubsubsec Cyclical Entries
4952 @cindex appointments, cyclic schedule entries
4954 You can also have cyclical schedule entries(@pxref{Cyclic Tasks}) if you
4958 (planner-appt-schedule-cyclic-insinuate)
4961 @noindent to your configuration.
4963 If you put an entry in your cyclical task file like this
4966 Friday @@12:45 | 13:45 | Staff Meeting
4970 then it will appear in your schedule every Friday, and an
4971 appointment alert will be set up.
4973 @node Viewing Appointments, Appointment Updating on Save, Schedule-based Appointments, Appointments
4974 @comment node-name, next, previous, up
4975 @subsubsection Viewing Appointments
4976 @cindex appointments, viewing
4978 The command @command{planner-appt-show-alerts} will show all appointment
4979 alerts currently scheduled.
4981 @subheading Functions
4983 There are two commands that show appointments in the future; the one
4984 displays them in a pop-up buffer, the other puts the information into
4985 the current day page.
4987 @deffn {Command} planner-appt-forthcoming-display &optional days
4988 Display a buffer of appointments for today and the next
4989 @var{days}. Optional prefix argument @var{days} is the number of days
4990 ahead to look. Its default value is defined by
4991 @code{planner-appt-forthcoming-days}.
4994 @deffn {Command} planner-appt-forthcoming-update-section &optional days
4995 In today's plan page, add or update a list of forthcoming
4996 appointments. Optional prefix argument @var{days} is the number of
4997 days ahead to look. Its default value is defined by
4998 @code{planner-appt-forthcoming-days}. The section heading to use is
4999 defined by @code{planner-appt-forthcoming-appt-section}.
5004 @defopt planner-appt-forthcoming-days
5005 The number of days to look ahead for forthcoming appointments. The
5006 default value is seven days.
5009 @defopt planner-appt-forthcoming-appt-section
5010 The name of the section to use for inserting a list of forthcoming
5011 appts. The default value is @code{"Forthcoming Appointments"}.
5014 @defopt planner-appt-forthcoming-show-day-names-flag
5015 When non-nil (the default), day names will be shown in forthcoming
5019 @defopt planner-appt-forthcoming-repeat-date-string
5020 String to insert for repeated dates.
5022 When there are multiple appointments for a date, the date is inserted
5023 in the first appointment and the others have this string in their date
5026 If the string consists of anything other than whitespace, then a link
5027 to the day page for the appoinment is created.
5030 @defopt planner-appt-forthcoming-look-at-cyclic-flag
5031 When non-nil, find forthcoming appointments in the cyclic diary file
5032 (@pxref{Cyclic Tasks}) as well as in plan pages. Default is @samp{t}.
5035 @node Appointment Updating on Save, Appointment and Calendar Integration, Viewing Appointments, Appointments
5036 @comment node-name, next, previous, up
5037 @subsubsection Appointment Updating on Save
5038 @cindex appointments, updating on save
5042 @defopt planner-appt-update-appts-on-save-flag
5043 When non-nil, update appointment reminders whenever today's plan page is
5044 saved. Default value is @samp{nil}.
5047 @node Appointment and Calendar Integration, Appointment Hooks, Appointment Updating on Save, Appointments
5048 @comment node-name, next, previous, up
5049 @subsubsection Appointment and Calendar Integration
5051 Not strictly part of appointment handling, but if one isn't using
5052 the diary, marking dates with plan pages seems to make sense.
5054 @subheading Functions
5056 @defun planner-appt-calendar-insinuate
5057 Add a hook to diary display so that dates in the calendar that have day
5058 pages are highlighted
5061 @node Appointment Hooks, , Appointment and Calendar Integration, Appointments
5062 @comment node-name, next, previous, up
5063 @subsubsection Appointment Hooks
5067 @defvr {Hook} planner-appt-update-hook
5068 Hook run after @code{planner-appt-update} has updated the appointment
5072 @node Timeclock, schedule.el, Appointments, Scheduling and Time
5073 @comment node-name, next, previous, up
5074 @subsection Timeclock
5075 @cindex @file{planner-timeclock.el}, using
5076 @cindex @file{planner-timeclock-summary.el}, using
5077 @cindex @file{planner-timeclock-summary-proj.el}, using
5078 @cindex timeclock, using Planner with
5080 This module allows you to clock in and clock out of your projects
5081 (@pxref{Time Intervals, , , Emacs, GNU Emacs Manual}) You can also
5082 generate reports with the @code{<timeclock-report>} tag. You may want to
5083 read the ``Keeping Track of Time'' page to see how you can use
5084 planner-timeclock to produce detailed reports;
5085 @xref{Keeping Track of Time}.
5087 @file{timeclock.el} is part of GNU Emacs. If you are using XEmacs,
5088 please use the version of @file{timeclock.el} that comes with Planner in
5089 the @file{contrib} directory.
5091 With @file{planner-timeclock.el} loaded,
5092 @command{planner-task-in-progress} clocks in a task. To clock out,
5093 use @command{planner-task-done} or @command{timeclock-out}.
5095 @file{planner-timeclock.el} defines the following keybindings:
5098 @item @kbd{C-c C-i}: @code{planner-task-in-progress}.
5099 @item @kbd{C-c C-o}: @code{timeclock-out}.
5100 @item @kbd{C-c C-T C-i}: @code{planner-timeclock-in}. (XEmacs)
5101 @item @kbd{C-c C-T C-o}: @code{timeclock-out}. (XEmacs)
5102 @item @kbd{C-c C-S-t C-i}: @code{planner-timeclock-in}. (GNU Emacs)
5103 @item @kbd{C-c C-S-t C-o}: @code{timeclock-out}. (GNU Emacs)
5106 If you use @code{timeclock} a lot, you may also be interested in
5107 Dryice Liu's @file{planner-timeclock-summary.el}, which produces
5108 timeclock reports for planner files.
5110 Here is a sample report:
5113 Project | Time| Ratio| Task
5114 PlannerMaintenance | 0:03:58| 1.1%| Merge doc patch
5115 | 0:17:09| 5.0%| Track down subdirectories
5116 | 0:18:11| 5.3%| Merge planner-timeclock-summary-proj.el
5117 Total: | 0:39:18| 11.4%|
5118 JapanCaseStudy | 2:37:56| 45.6%| Prototype search result page
5119 | 0:31:50| 9.2%| Update design documents
5120 Total: | 3:09:46| 54.8%|
5121 ChristmasLetter | 1:46:37| 30.8%| Write and send my Christmas letters
5122 Total: | 1:46:37| 30.8%|
5123 LinuxPeople | 0:10:29| 3.0%| Send questions for Linux in Education
5124 Total: | 0:10:29| 3.0%|
5127 If you add @code{(require 'planner-timeclock-summary)} to your
5128 @file{~/.emacs}, you can then use it in two ways.
5132 @item Display a temporary buffer
5134 Call @code{planner-timeclock-summary-show} and Emacs will ask you which
5135 day's summary do you want. Choose the date as anywhere else of
5136 Emacs planner, and a tempory buffer will be displayed with the
5137 timeclock summary of that day.
5139 To review tasks over a date range, use
5140 @code{planner-timeclock-summary-show-range}. You can use a regexp or a
5141 function to filter tasks by calling
5142 @code{planner-timeclock-summary-show-range-filter}.
5144 @item Rewrite sections of your planner
5146 Choose this approach if you want timeclock summary to be in their
5147 own section and you would like them to be readable in your plain
5148 text files even outside Emacs. Caveat: The timeclock summary
5149 section should already exist in your template and will be rewritten
5150 when updated. Tip: Add @code{planner-timeclock-summary-section}
5151 (default: @samp{"Timeclock"}) to your @code{planner-day-page-template}.
5153 To use, call @code{planner-timeclock-summary-update} in the planner
5154 day page to update the section. If you want rewriting to be
5155 automatically performed, call
5156 @code{planner-timeclock-summary-insinuate} in your @file{.emacs} file.
5159 @file{planner-timeclock-summary-proj.el} produces task / time
5160 breakdowns on plan pages. Reports are of the form:
5168 To use, add @code{(require 'planner-timeclock-summary)} to your
5169 @file{~/.emacs}. Call @code{planner-timeclock-summary-proj-current}
5170 from a project page. The report is inserted at the current position in
5171 the buffer. The function @code{planner-timeclock-summary-proj-section}
5172 does the same but the report is inserted inside a section called
5175 @node schedule.el, , Timeclock, Scheduling and Time
5176 @comment node-name, next, previous, up
5177 @subsection @file{schedule.el}
5178 @cindex @file{planner-schedule.el}, using
5179 @cindex @file{schedule.el}, using Planner with
5181 @file{planner-schedule.el} allows you to project task completion time.
5182 Tasks should be of the form:
5185 #A0 _ 2h Do something
5186 #B0 _ 1h30m Do something
5187 #B0 _ 2d Do something
5188 #B0 _ 2w Do something
5189 #B0 _ 10s Do something
5191 s: seconds, m: minutes, h: hours, d: days, w: weeks
5194 @file{schedule.el} is included with Planner in the @file{contrib}
5195 directory, but you can alternatively get it from
5196 @url{http://www.newartisans.com/johnw/Emacs/schedule.el} if desired.
5198 @file{schedule.el} provides a single Lisp function,
5199 @code{schedule-completion-time}. It takes an Emacs time object and a
5200 quantity of seconds. It returns an Emacs time object that represents
5201 when the given number of seconds will be completed, assuming that work
5202 can only be done during work hours.
5204 The available work hours are affected by several factors:
5209 If @file{timeclock.el} is being used, the amount of time left in the
5210 current work day (@code{timeclock-workday-remaining})
5211 (@pxref{Time Intervals, , , Emacs, GNU Emacs Manual})
5214 The amount of time in each work day (@code{schedule-workday})
5217 The definition of a work week (@code{schedule-week})
5220 Any holidays defined in the Emacs calendar
5221 (@pxref{Holidays, , , Emacs, GNU Emacs Manual})
5224 Any appointments in the Emacs diary
5225 (@pxref{Appointments, , , Emacs, GNU Emacs Manual})
5229 Taking all of the ``block out'' periods into account,
5230 @code{schedule-completion-time} will compute when the given number of
5231 seconds will be done, based on your current definitions of time
5234 As an example, here's a function which, given a list of durations
5235 in seconds, will return a list of completion times starting from
5240 (defun compute-completion-times (&rest durations)
5241 ``Compute completion times for a list of DURATIONS (in seconds).''
5242 (let ((now (current-time)))
5246 (setq now (schedule-completion-time now dura))))
5251 To call this function, do:
5255 (compute-completion-times 3600 7200 3600)
5261 @file{planner-schedule.el} defines the following keybindings:
5263 @kbd{C-c RET} is bound to @command{planner-schedule-show-end-project}.
5264 @kbd{C-c C-m} is also bound to
5265 @command{planner-schedule-show-end-project}.
5267 In XEmacs, @command{planner-schedule-show-end-project} is bound to
5268 @kbd{C-c C-T c-e} and @kbd{C-c C-S-t C-e}.
5270 @subheading Functions
5272 @file{planner-schedule.el} defines the following interactive
5275 @defun planner-schedule-show-end-project
5276 Display the estimated project completion time.
5279 @file{schedule.el} does not define any interactive functions, or
5282 @node Finances, Contacts and Conversations, Scheduling and Time, Managing Your Information
5283 @comment node-name, next, previous, up
5287 Currently, Planner provides one module dedicated to tracking your
5288 finances. This module works with a program called Ledger.
5291 * Ledger:: Personal finances: planner-ledger.el
5294 @node Ledger, , Finances, Finances
5295 @comment node-name, next, previous, up
5298 @cindex @file{planner-ledger.el}, using
5299 @cindex @file{ledger}, using Planner with
5301 @file{planner-ledger.el} provides integration between planner and John
5302 Wiegley's ledger accounting program, which can be found at
5303 @url{http://newartisans.com/johnw/ledger.tar.gz}.
5305 To use planner-ledger to insert a ledger balance overview and a list
5306 of pending transactions into planner day pages, make sure that your
5307 day page includes sections that match
5308 @code{planner-ledger-balance-regexp} and
5309 @code{planner-ledger-pending-regexp}. Example:
5316 ** Pending transactions
5322 You can manually update ledger sections with the
5323 @command{planner-ledger-insert-maybe} command.
5325 You can also automatically update ledger sections with the following
5329 (add-hook 'planner-goto-hook 'planner-ledger-insert-maybe)
5332 You can create ledger entries from specially-formatted tasks using
5333 @command{planner-ledger-add-entry-from-task}. Tasks should be of the
5334 form @samp{payment due: payee, amount [comment]}. Example:
5337 #A1 _ payment due: foobar, $1000.00 some comment here
5338 #A2 _ payment due: baz, 1000.00
5343 @defopt planner-ledger-balance-accounts
5344 List of accounts to be included or excluded from the balance overview.
5345 @samp{+} includes all matching accounts, and @samp{-} excludes
5346 matching accounts. See the documentation for
5347 @command{ledger-run-ledger} for more details.
5350 @defopt planner-ledger-balance-regexp
5351 Regular expression matching section for ledger balance. Do not store
5352 other data in this section, as it will be overwritten.
5355 @defopt planner-ledger-pending-regexp
5356 Regular expression matching section for ledger balance. Do not store
5357 other data in this section, as it will be overwritten.
5360 @defopt planner-ledger-payment-task-regexp
5361 Regular expression matching special ledger tasks.
5364 @subheading Functions
5366 @defun planner-ledger-insert-maybe
5367 Update any ledger sections on the current page.
5370 @defun planner-ledger-add-entry-from-task
5371 Create a ledger entry based on the task at point. Task should match
5372 @code{planner-ledger-payment-task-regexp}.
5375 @node Contacts and Conversations, Tracking Research and Resources, Finances, Managing Your Information
5376 @comment node-name, next, previous, up
5377 @section Contacts and Conversations
5379 @cindex conversations
5381 Planner has two modules available for keeping track of contact and
5382 conversation information. The first uses the Big Brother Database
5383 (BBDB), and the second uses Emacs Relay Chat (ERC). BBDB is a full
5384 contact database. ERC is a client for chatting online on Internet Relay
5385 Chat (IRC) networks. The ERC module for Planner will help you keep
5386 track of online conversations you have if you use ERC for those
5387 conversations, but does not by itself store contact information other
5388 than the time you had the conversation, the network and channel you were
5389 on when you had it, and maybe who you had it with. If you are looking
5390 for a way to manage your full address book, then @file{planner-bbdb.el}
5391 in combination with BBDB is what you are looking for.
5394 * BBDB:: Contacts: planner-bbdb.el
5395 * Emacs Relay Chat:: Internet Relay Chat: planner-erc.el
5398 @node BBDB, Emacs Relay Chat, Contacts and Conversations, Contacts and Conversations
5399 @comment node-name, next, previous, up
5401 @cindex @file{planner-bbdb.el}, using
5402 @cindex BBDB, using Planner with
5404 @file{planner-bbdb.el} allows you to refer to your contacts easily
5405 from within a planner page. @inforef{Top, the BBDB Manual, bbdb}.
5407 @samp{[[bbdb://Sacha.*Chua][Sacha]]}, for example, will be linked to
5408 the blog, web or net fields of the first matching BBDB record.
5410 @file{planner-bbdb.el} does not define any interactive functions, or
5413 @node Emacs Relay Chat, , BBDB, Contacts and Conversations
5414 @comment node-name, next, previous, up
5415 @subsection Emacs Relay Chat
5416 @cindex @file{planner-erc.el}, using
5417 @cindex ERC, using Planner with
5418 @cindex Emacs Relay Chat, using Planner with
5419 @cindex IRC, using Planner with
5420 @cindex Internet Relay Chat, using Planner with
5422 To use planner-erc, place @file{planner-erc.el} in your load path
5423 and add this to your @file{.emacs} (or @file{_emacs}):
5427 (require 'planner-erc)
5431 IRC URLs may be of the following forms.
5434 irc://server/nick,isnick
5435 irc://server/#channel
5439 Annotations will be in the following forms.
5442 [[irc://server/nick,isnick][Chat with nick on server#channel]]
5443 [[irc://server/nick,isnick][Chat with nick on server]]
5444 [[irc://server/#channel][Chat on server#channel]]
5445 [[irc://server][Chat on server]]
5448 @file{planner-erc.el} does not define any interactive functions, or
5451 @node Tracking Research and Resources, Tracking Development, Contacts and Conversations, Managing Your Information
5452 @comment node-name, next, previous, up
5453 @section Tracking Research and Resources
5455 Planner provides three modules for keeping track of information
5456 involving three specific tools: w3m, BibTeX, and @file{bookmark.el}.
5459 * W3m:: Web browser: planner-w3m.el
5460 * BibTeX:: Bibliographies: planner-bibtex.el
5461 * Bookmark:: Bookmarks: planner-bookmark.el
5464 @node W3m, BibTeX, Tracking Research and Resources, Tracking Research and Resources
5465 @comment node-name, next, previous, up
5467 @cindex @file{planner-w3m.el}, using
5468 @cindex w3m, using Planner with
5470 This module allows you to create tasks from a w3m buffer.
5472 @file{planner-w3m.el} does not define any interactive functions, or
5475 @node BibTeX, Bookmark, W3m, Tracking Research and Resources
5476 @comment node-name, next, previous, up
5478 @cindex @file{planner-bibtex.el}, using
5480 BibTeX URLs are of the form @samp{bibtex:file/name:key}.
5482 @file{planner-bibtex.el} does not define any interactive functions.
5484 @node Bookmark, , BibTeX, Tracking Research and Resources
5485 @comment node-name, next, previous, up
5486 @subsection Bookmark
5488 @cindex @file{bookmark.el}, using Planner with
5489 @cindex @file{planner-bookmark.el}, using
5491 @file{planner-bookmark.el} uses the @file{remember} package to create a
5492 note whenever you create a bookmark (see @inforef{Bookmarks, Bookmarks,
5493 Emacs}). For more information about @file{remember}, please check out
5497 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} -
5500 @uref{http://sacha.free.net.ph/notebook/doc/dev/remember/remember.html}
5501 - Online info documentation
5504 Configure remember according to the instructions in
5505 @file{remember-planner.el} so that notes are saved to your planner
5508 @defopt planner-bookmark-take-note-after-set-bookmark-flag
5509 Non-nil means show a @code{remember} buffer after setting a new
5513 When you create a bookmark, Emacs will open a buffer for your notes.
5514 @kbd{C-c C-c} saves the buffer to today's page. If you don't want to
5515 save a note, you can kill the buffer.
5517 Bookmark URLs are of the form @samp{bookmark://bookmark-name}.
5519 @file{planner-bookmark.el} does not define any interactive functions.
5521 @node Tracking Development, , Tracking Research and Resources, Managing Your Information
5522 @comment node-name, next, previous, up
5523 @section Tracking Development
5524 @cindex version control, using Planner with
5526 Planner has three modules geared toward programmers. Two modules deal
5527 with version control and integrating information from those projects
5528 into the planner page. One module deals with the Gnats bug-tracking
5532 * Log Edit:: Changelogs: planner-log-edit.el
5533 * PSVN:: svn changesets: planner-psvn.el
5534 * XTLA:: TLA changesets: planner-xtla.el
5535 * Gnats:: Gnats: The GNU bug reporting system
5538 @node Log Edit, PSVN, Tracking Development, Tracking Development
5539 @comment node-name, next, previous, up
5540 @subsection Log Edit
5541 @cindex cvs, using Planner with
5542 @cindex @file{planner-log-edit.el}, using
5543 @cindex version control, using Planner with
5545 This module allows you to automatically record CVS (and VC) commits
5548 You can load the module with @code{(require 'planner-log-edit)}. When
5549 you load the module, @code{planner-log-edit-add-note} will be added to
5550 @code{log-edit-done-hook}. A note containing the text of the commit
5551 and optionally a list of modified files will be added to today's page
5552 if you use the the Emacs version control interface. (@pxref{Version
5553 Control, , , Emacs, GNU Emacs Manual})
5557 @defopt planner-log-edit-include-files-flag
5558 Non-nil means include a list of committed files in the note.
5561 @defopt planner-log-edit-notice-commit-function
5562 Non-nil means include a list of committed files in the note. If you
5563 want to enable this feature for some projects but not for others, set
5564 this to a function that returns t only for the commits you want to
5568 @file{planner-log-edit.el} does not define any interactive functions.
5570 @node PSVN, XTLA, Log Edit, Tracking Development
5571 @comment node-name, next, previous, up
5574 @cindex @file{planner-psvn.el}, using
5575 @cindex Subversion, integration with
5577 This module enables you to refer to your Subversion (svn) changesets
5578 easily from within a Planner page, and to have your svn commits recorded
5579 automatically as notes in your planner.
5581 You must also have @file{psvn.el}, which is often packaged with
5582 Subversion in GNU/Linux distributions.
5584 You can then load the module by adding @code{(require 'planner-psvn)} to
5585 your @file{~/.emacs}.
5587 Once the module is loaded, Planner will pick up annotation information
5588 from any psvn *svn-log-view* buffer. If you create a task or note while
5589 in such a buffer, that task will have a hyperlink you can follow to
5590 return to the changeset later.
5592 These hyperlinks are of the form
5593 @samp{psvn://http://my.svn-repos.at/svn/project1/trunk@@39}
5595 Additionally, you can have notes for your commits automatically
5596 generated. Set @var{planner-psvn-log-edit-notice-commit-function} to t
5599 By default, these commit notes will include a list of the files
5600 modified. If you would prefer to have this list not included, set
5601 @var{planner-psvn-log-edit-include-files-flag} to nil.
5603 @node XTLA, Gnats, PSVN, Tracking Development
5604 @comment node-name, next, previous, up
5607 @cindex @file{planner-xtla.el}, using
5609 This module allows you to refer to changesets in Tom Lord's Arch (tla)
5610 version control system. You can load the module with @code{(require
5611 'planner-xtla)}. When you load the module, you can create tasks from
5612 XTLA windows by positioning point on a revision.
5614 XTLA URLs are of the form
5615 @samp{xtla://miles@@gnu.org--gnu-2005/emacs--cvs-trunk--0--patch-19}
5617 @file{planner-xtla.el} does not define any interactive functions.
5619 @node Gnats, , XTLA, Tracking Development
5620 @comment node-name, next, previous, up
5624 @cindex @file{planner-gnats.el}, using
5625 @cindex bug reports, tracking
5627 @file{planner-gnats.el} provides support for the GNU problem report
5628 management system Gnats. This module allows you to refer to problem
5629 reports using hyperlinks.
5631 Configure your Emacs for Gnats access, then add @samp{(require
5632 'planner-gnats)} to your @file{.emacs}. You can then create tasks from
5633 Gnats edit or view buffers.
5635 To add keybindings to Gnats, use @samp{(planner-gnats-insinuate)}.
5637 Gnats URLs are of the form @samp{gnats:pr-number}.
5639 @file{planner-gnats.el} does not define any interactive functions.
5641 @node Advanced Configuration, Reference Material, Managing Your Information, Top
5642 @comment node-name, next, previous, up
5643 @chapter Advanced Configuration
5644 @cindex configuration, advanced
5647 * Customizing Your Day Pages:: Change your templates
5648 * Variables to Customize:: Change various aspects of Planner behavior
5649 * Ideas for Other Keybindings:: Add to and change the default keybindings
5652 @node Customizing Your Day Pages, Variables to Customize, Advanced Configuration, Advanced Configuration
5653 @comment node-name, next, previous, up
5654 @section Customizing Your Day Pages
5656 With the variable @code{planner-day-page-template}, you can define how
5657 you want any newly created day planner pages to look.
5659 You might want to include a section for your diary entries. For how to
5660 do this, see @ref{Diary}.
5662 You can add interactive Lisp buttons with the @file{planner-lisp.el}
5663 module. (@pxref{Interactive Lisp})
5665 Your @code{planner-day-page-template} can also include @samp{|<lisp>|}
5668 For more complex day pages, you can set
5669 @code{planner-day-page-template} to a function that will be called
5670 from an empty day page buffer. The function should initialize the
5671 contents of the day page.
5673 @node Variables to Customize, Ideas for Other Keybindings, Customizing Your Day Pages, Advanced Configuration
5674 @comment node-name, next, previous, up
5675 @section Variables to Customize
5676 @cindex customize, variables to
5677 @cindex variables, customization of
5678 @cindex configuration, advanced, variables
5680 If you want to change @code{planner-directory} and some other
5681 variables, either use Customize (@kbd{M-x customize-group RET planner
5682 RET}) or use @code{setq}. An example of the latter follows.
5685 (setq planner-directory "~/Plans")
5688 Other user options are:
5690 @vindex planner-use-day-pages
5691 @defopt planner-use-day-pages
5692 If you really don't like day pages, you can set this variable to nil
5693 and you won't be prompted for dates for tasks (and notes, if using
5694 @file{remember-planner}).
5697 @vindex planner-use-plan-pages
5698 @defopt planner-use-plan-pages
5699 If you really don't like plan pages, you can set this variable to nil
5700 and you won't be prompted for plan pages for tasks (and notes, if
5701 using @file{remember-planner}).
5704 @vindex planner-mode-hook
5705 @defopt planner-mode-hook
5706 List of functions to run after @code{planner-mode} is initialized.
5709 @vindex planner-tasks-file-behavior
5710 @defopt planner-tasks-file-behavior
5711 This variable controls what happens to files Planner opens by itself.
5712 If your tasks are associated with plan pages, the plan pages are
5713 updated whenever a task is rescheduled. This could lead to a lot of
5714 open buffers as Planner applies updates to all linked files.
5715 By default, Planner is configured to do nothing.
5716 A value of @samp{save} means save but do not close buffers, and a
5717 value of @samp{nil} means do not save any of the buffers.
5720 @vindex planner-add-task-at-end-flag
5721 @defopt planner-add-task-at-end-flag
5722 This variable controls where new tasks are created. Non-nil means
5723 create tasks at the bottom of the first task block. If you set this
5724 to non-nil, new tasks will be listed in order of creation (oldest).
5725 Tasks carried over from previous days will appear at the bottom of the
5728 Nil means create tasks at the top of the first task block.
5729 Carried-over tasks and newly created tasks are prominently placed on
5730 top of the list of tasks for the day.
5733 @vindex planner-default-page
5734 @defopt planner-default-page
5735 Default page for created tasks. This is used as the initial value for
5736 tasks. After you create a task, it will be set to the previous page
5740 @vindex planner-hide-task-status-when-highlighting
5741 @defopt planner-hide-task-status-when-highlighting
5742 Font-locking for tasks may be enough for you to determine status and
5743 priority. Set this to non-nil if you want to hide the status marker
5744 and rely on font-locking instead.
5747 @vindex planner-create-task-hook
5748 @defopt planner-create-task-hook
5749 Functions run after creating a task. @code{planner-id} hooks into
5753 @vindex planner-expand-name-favor-future-p
5754 @defopt planner-expand-name-favor-future-p
5755 If non-nil, partial dates (ex: @kbd{2} or @kbd{5.2}) are completed to
5756 dates in the future instead of using the current year and month.
5759 @vindex planner-task-dates-favor-future-p
5760 @defopt planner-task-dates-favor-future-p
5761 Like @code{planner-expand-name-favor-future-p}, but only for tasks.
5764 @vindex planner-publish-dates-first-p
5765 @defopt planner-publish-dates-first-p
5766 Non-nil means list day pages first in the planner index.
5769 @node Ideas for Other Keybindings, , Variables to Customize, Advanced Configuration
5770 @comment node-name, next, previous, up
5771 @section Ideas for Other Keybindings
5772 @cindex keybindings, customization of
5773 @cindex configuration, advanced, keybindings
5774 @cindex customize, keybindings to
5776 By default and for backward compatibility, the following operations
5777 do not have keybindings, and are only accessible from the Planner
5783 @code{planner-copy-or-move-region}
5786 @code{planner-delete-task}
5789 @code{planner-task-delegated}
5792 @code{planner-task-pending}
5795 @code{planner-task-open}
5798 @code{planner-renumber-tasks}
5802 You may find it easier to install keybindings for those operations by
5803 inserting the following in your @file{.emacs} (or @file{_emacs}).
5804 Note: This changes some of the default keybindings for Planner.
5807 (planner-install-extra-task-keybindings)
5810 If you install the extra task keybindings, your keybindings will
5816 @kbd{C-c C-t} will be unbound from the default and will serve as the
5817 prefix for the other task keybindings.
5820 @kbd{C-c C-t C-t}: @code{planner-create-task-from-buffer}.
5823 @kbd{C-c C-t C-k}: @code{planner-delete-task}.
5826 @kbd{C-c C-t C-u}: @code{planner-update-task}.
5829 @kbd{C-c C-t C-c}: @code{planner-copy-or-move-task}.
5832 @kbd{C-c C-t C-S-c}: @code{planner-copy-or-move-region}.
5835 @kbd{C-c C-t C-x}: @code{planner-task-done}.
5838 @kbd{C-c C-t C-S-x}: @code{planner-task-cancelled}.
5841 @kbd{C-c C-t C-d}: @code{planner-task-delegated}.
5844 @kbd{C-c C-t C-p}: @code{planner-task-pending}.
5847 @kbd{C-c C-t C-o}: @code{planner-task-in-progress}.
5850 @kbd{C-c C-t C-r}: @code{planner-raise-task}.
5853 @kbd{C-c C-t C-l}: @code{planner-lower-task}.
5856 @kbd{C-c C-t C-n}: @code{planner-renumber-tasks}.
5860 Other keybindings can be configured by adding this to your
5861 @file{.emacs} (or @file{_emacs}):
5864 (planner-install-extra-context-keybindings)
5867 This will set up the following keybindings:
5872 @kbd{shift up} @code{planner-move-up}
5875 @kbd{shift down} @code{planner-move-down}
5878 @kbd{shift right} @code{planner-jump-to-link}
5882 @node Reference Material, Getting Help, Advanced Configuration, Top
5883 @comment node-name, next, previous, up
5884 @chapter Reference Material
5887 * Keeping Track of Time::
5888 * Other Interactive Functions::
5889 * Planner Keybindings:: Default keybindings for Planner
5890 * Sample Configuration Files::
5893 @node Keeping Track of Time, Other Interactive Functions, Reference Material, Reference Material
5894 @section Keeping Track of Time
5896 One of the coolest things you can do with Planner is keep track of how
5897 much time you spend not only on projects but even on particular tasks.
5898 @file{planner-timeclock.el} makes it as easy and natural as marking a
5899 task as in progress, postponed, or done. This can help you determine
5900 just how much time you spend working each day. If you add estimates to
5901 your task descriptions, you'll also be able to use this information to
5902 improve your time estimation skills.
5904 Here's how you can keep track of the time you
5907 Then the fun began. I wanted to see if I could match my estimates.
5908 Before I started working on a task, I used @kbd{C-c TAB} to mark it
5909 @code{in progress} and start the clock. If I decided to work on
5910 something else, I used @kbd{C-c TAB} to clock out of the previous task
5911 and clock into the new one.
5913 When I finished it, I used @kbd{C-c C-x} (@code{planner-task-done}) to
5914 mark it completed and automatically clock out. This is not yet done
5915 for cancelled tasks, so I clocked out of those manually with @kbd{C-c
5916 C-o} (@code{timeclock-out}). I also clocked out whenever I caught
5917 myself being distracted so that the totals wouldn't include the time I
5918 spent chatting on #emacs or checking out del.icio.us links. =) At the
5919 end of the day, I used
5920 @code{planner-timeclock-summary-show-range-filter} to show me the time
5921 elapsed for all of the tasks I'd worked on over the past two days.
5922 Here's the report for that project, edited to reflect how it looks on
5923 my screen and annotated with comments:
5926 Timeclock summary report for 2004.12.28 - 2004.12.29
5928 Project | Time| Ratio| Task
5929 JapanProject| 0:23:17| 3.6%| Translate javadoc comment for Messages.java
5930 | 0:33:48| 5.3%| Translate javadoc comment for LoginAction.java
5931 | 1:54:07| 17.8%| Study Struts in Japanese
5932 | 0:46:08| 7.2%| Add javadoc tags for input, output and forwards
5933 | 1:03:48| 9.9%| Help review code
5934 | 0:04:14| 0.7%| Import todo list
5935 | 0:00:37| 0.1%| 2min Fix Menu Action's unnecessary code - delegated
5936 | 0:01:01| 0.2%| 2min Remove unnecessary list in UserRemoveSetupAction - cancelled
5937 | 0:02:10| 0.3%| 2min Remove hard-coded database path from MenuAction
5938 | 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. ...
5939 | 0:07:32| 1.2%| 5min Add a method that returns the validity of a user in MUserPeer.
5940 | 0:08:28| 1.3%| 5min Fix indentation
5941 | 0:03:52| 0.6%| 10min Fix UserPeer so that it doesn't get null pointer exceptions
5942 | 0:04:34| 0.7%| 5min Add current password field in user_modify page
5943 | 0:21:56| 3.4%| 15min Make a super class for our service classes that will receive the database connection. (cancelled)
5944 | 0:06:05| 0.9%| 10min Remove hard-coded constants from the Logic classes
5945 | 0:10:55| 1.7%| 10min Move logic from UserBean.checkPassword to UserListLogic
5946 | 0:01:20| 0.2%| 20min Guard against null pointer exceptions in peer classes
5947 | 0:04:57| 0.8%| 10min Instead of displaying uneditable data with bean:write, just disable the html:text element
5948 | 0:25:03| 3.9%| 10min Deploy 10:00 version
5949 | 0:04:46| 0.7%| 5min Separate the configuration file of database and system into another uninternationalized property file.
5950 | 2:09:48| 20.2%| 1h Decide on a naming convention for localized messages and update files
5951 | 0:00:07| 0.0%| 20min Explain what is happening in UserModifyAction's nested ifs - pending
5952 | 1:50:23| 17.2%| 2h Write Javadoc comments in English and Japanese to explain bean structure
5953 | 0:04:19| 0.7%| 2h Write Javadoc comments in English and Japanese to explain peer operations (pending)
5954 | 0:05:40| 0.9%| 20min Make a factory class for the database - pending
5955 Total: | 10:41:41|100.0%|
5957 Day began: 13:03:58, Day ended: 20:51:46
5958 Time elapsed: 31:47:48, Time clocked: 10:41:41
5959 Time clocked ratio: 33.6%
5962 The time record isn't perfect. I cancelled some tasks after thinking
5963 about them a little and did some tasks simultaneously. Sometimes I
5964 didn't notice that I was getting distracted, too. Still, having all of
5965 that time information neatly summarized made me realize a number of
5968 First, I goof off much less when I have a nice, broken-down task list
5969 in front of me. There's just something about knowing there's a five-
5970 or ten-minute hack you can get out of the way. I found myself looking
5971 forward to getting to the next task just to see if I could make my
5972 estimate. That said, seeing a five-minute task stretch and stretch due
5973 to unforeseen problems did make me a little nervous. I should probably
5974 just make generous estimates so that I don't end up with bugs because
5977 Second, I don't goof off as much as I thought I did, although there's
5978 still room for improvement. Yesterday's workday was 9:00 - 12:00, 1:00
5979 - 5:30--7.5 hours. Today was the last day of work, so cleaning and
5980 celebration interrupted my hacking at around 3:00--5 hours of work.
5981 According to my task list, 10:41/12:30 was productive work. Hmm. 1:49
5982 hours unclocked time when I was thinking or goofing off.
5983 planner-timeclock-summary-show for today reveals that I actually
5984 clocked 5:30 today, which means the goofing off happened yesterday.
5985 That makes sense; I remember a pretty long unclocked segment
5986 recuperating from Japanese overload. (This was before we came up with
5989 Third, keeping track of time is way, way cool even if you don't bill
5990 anyone for your time.
5992 Like the idea? It's easy to try out. Just add
5995 (require 'planner-timeclock)
5996 (require 'planner-timeclock-summary)
5999 to your ~/.emacs. If you want to try it out now, eval those statements
6000 in your Emacs session. After that, simply use @kbd{C-c TAB} to ``clock
6001 in'' a task before you start working on it and @kbd{C-c C-x}
6002 (@code{planner-task-done}) to mark it completed. @kbd{M-x
6003 planner-task-pending} also clocks out the current task if it was
6004 clocked in. To see a summary of how you spent your day, check out the
6005 different functions in @file{planner-timeclock-summary}.
6007 See @ref{Timeclock} for more details.
6011 @node Other Interactive Functions, Planner Keybindings, Keeping Track of Time, Reference Material
6012 @comment node-name, next, previous, up
6013 @section Other Interactive Functions
6015 With @file{planner.el} loaded, you can use any of the functions in this
6016 section by typing @kbd{M-x} followed by the name of the function. Many
6017 of these functions are also bound to keys.
6019 For a list of Planner keybindings, see @ref{Planner Keybindings}.
6021 They are listed in no particular order.
6023 @file{planner.el} defines the following interactive functions:
6026 @defun planner-create-high-priority-task-from-buffer
6027 Create a high priority task based on this buffer. Do not use this in
6028 LISP programs. Instead, set the value of
6029 @var{planner-default-task-priority} and call @code{planner-create-task}
6030 or @code{planner-create-task-from-buffer}.
6033 @defun defun planner-create-medium-priority-task-from-buffer
6034 Create a medium-priority task based on this buffer. Do not use this in
6035 LISP programs. Instead, set the value of
6036 @var{planner-default-task-priority} and call @code{planner-create-task}
6037 or @code{planner-create-task-from-buffer}.
6040 @defun planner-create-low-priority-task-from-buffer
6041 Create a high-priority task based on this buffer.
6042 Do not use this in LISP programs. Instead, set the value of
6043 @var{planner-default-task-priority} and call @code{planner-create-task} or
6044 @code{planner-create-task-from-buffer}.
6047 @defun planner-install-extra-context-keybindings
6048 Install extra context-sensitive keybindings. These keybindings
6049 conflict with @file{windmove.el}, but might be useful.
6052 @defun planner-narrow-to-section section &optional create
6053 Widen to the whole page and narrow to the section labelled
6054 @var{section}. If @var{create} is non-nil and the section is not found,
6055 the section is created. Return non-nil if @var{section} was found or
6059 @defun planner-save-buffers
6060 Save all planner-mode buffers.
6063 @defun planner-seek-to-first section
6064 Positions the point at the specified @var{section}, or @samp{Tasks} if
6068 @defun planner-save-buffers
6069 Save all planner buffers.
6072 @defun planner-calendar-insinuate
6073 This hooks Planner into Emacs Calendar (@pxref{Calendar/Diary, ,
6074 , Emacs, GNU Emacs Manual}).
6076 It adds special planner key bindings to @code{calendar-mode-map}.
6077 After this function is evaluated, you can use the following
6078 planner-related keybindings in @code{calendar-mode-map}:
6083 Jump to the planner page for the current day.
6086 Display the planner page for the current day.
6091 @defun planner-kill-calendar-files
6092 Remove planner files shown from Calendar (@pxref{Calendar/Diary, , ,
6093 Emacs, GNU Emacs Manual}).
6097 @defun planner-calendar-goto
6098 Goto the plan page corresponding to the calendar date
6099 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6102 @defun planner-calendar-show
6103 Show the plan page for the calendar date under point in another window
6104 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6107 @defun planner-calendar-select
6108 Return to @code{planner-read-date} with the date currently selected
6109 (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}).
6112 @defun planner-jump-to-link
6113 Jump to the item linked to by the current item.
6116 @defun planner-move-up
6117 Move a task up. You can use this to indicate that you will do a task
6118 before another one. On a note, go to the previous note. On a headline,
6119 go to the previous headline of the same depth.
6122 @defun planner-move-down
6123 Move down. You can use this to indicate that you will do a task after
6124 another one. On a note, go to the next note. On a headline, go to the
6125 next headline of the same depth.
6128 @node Planner Keybindings, Sample Configuration Files, Other Interactive Functions, Reference Material
6129 @comment node-name, next, previous, up
6130 @section Planner Keybindings
6131 @cindex keybindings, list
6133 In order to refresh and renumber all of your tasks according to their
6134 actual order in the buffer, simply save the file or call
6135 @kbd{M-x planner-renumber-tasks}.
6137 Here is a summary of the keystrokes available:
6142 Begin your planning session. This goes to the last day for which
6143 there is any planning info (or today if none), allowing you to review,
6144 and create/move tasks from that day.
6153 Mark the task as in progress or delegated.
6156 Mark the task as finished.
6159 Create a task associated with the current Wiki page. If you are on the
6160 opening line of a Note entry, it is assumed that the note itself is the
6164 Move or copy the current task to another date. If the current task is
6165 an original (meaning you are in the buffer where's defined, hopefully
6166 a planning page) then it will be copied, and the original task will
6167 also now point to the copy. If the current task is a copy, it will
6168 just be moved to the new day, and the original task's link will be
6172 Jump to today's task page. If you call
6173 @code{(planner-calendar-insinuate)}, typing @kbd{n} in the Emacs
6174 calendar (@pxref{Calendar/Diary, , , Emacs, GNU Emacs Manual}) will jump
6175 to today's task page.
6178 @code{planner-task-done}
6181 @code{planner-task-in-progress}
6184 @code{planner-lower-task}
6187 @code{planner-raise-task}
6190 @code{planner-copy-or-move-task}
6193 @code{planner-create-task-from-buffer}
6196 This is a prefix command.
6199 @code{planner-goto-today}
6202 @code{planner-goto-most-recent}
6205 @code{planner-goto-tomorrow}
6208 @code{planner-goto-yesterday}
6211 @code{planner-goto-today}
6214 @code{planner-goto-next-daily-page}
6217 @code{planner-goto-previous-daily-page}
6224 @node Sample Configuration Files, , Planner Keybindings, Reference Material
6225 @comment node-name, next, previous, up
6226 @section Sample Configuration Files
6227 @cindex configuration, sample
6229 This section includes some sample configuration files. This way, once
6230 you've got the hang of the basics, you can see some different, more
6233 There is no One True Way to plan. Every person is different. We hope
6234 you'll find a good starting point among the example configurations
6235 below. If what you want to do does not perfectly fit under one of these
6236 examples, please post a description of the way you plan to our mailing
6237 list (@pxref{Getting Help}). We look forward to helping you customizing
6238 planner to fit your needs.
6241 * File Organization::
6242 * Bare-Bones Planning::
6243 * Bare-Bones Planning with Plan Pages::
6244 * Tasks on Plan Pages with Some Day Pages::
6245 * Hierarchical Tasks::
6248 @node File Organization, Bare-Bones Planning, Sample Configuration Files, Sample Configuration Files
6249 @subsection File Organization
6252 @item @strong{Tasks, schedule and notes on day pages.}
6254 By default, tasks, schedule entries and notes are filed on day pages.
6255 This makes it easy for you to see all the entries relevant to a single
6256 day without becoming overwhelmed with information. Unfinished tasks
6257 are carried over to the next day when you use @kbd{M-x plan}, so it's
6258 always kept up to date. Completed tasks are left on the day page you
6259 finished them on, which helps when reviewing one's progress and writing
6260 accomplishment reports.
6262 @item @strong{Cross-referenced with plan pages.}
6264 You can associate your tasks with projects either when you create the
6265 task or later, with @kbd{M-x planner-replan-task}. This makes it easy
6266 for you to see all the information associated with a particular
6267 project. If you use RememberMode to create notes, you will also be
6268 able to associate notes with a plan page.
6270 @item @strong{Just plan pages.}
6272 If your tasks don't usually have dates, you can turn day pages off by
6273 customizing @code{planner-use-day-pages}. If so, then all of your
6274 tasks and notes will be stored on the WelcomePage and/or a plan page.
6278 @node Bare-Bones Planning, Bare-Bones Planning with Plan Pages, File Organization, Sample Configuration Files
6279 @subsection Bare-Bones Planning
6281 You can keep all of your tasks, notes and schedules in a single file:
6282 WelcomePage. This is good for people who are used to storing all of
6283 their information in a flat text file. By storing your information in
6284 planner, you'll be able to take advantage of automatic hyperlinking to
6285 files and other resources. You can also sort your tasks by priority
6288 To set your system up for bare-bones planning, set the
6289 @code{planner-use-day-pages} variable to nil before loading planner.
6290 For example, you can put this in your @file{~/.emacs} (or @file{_emacs}):
6293 (setq planner-use-day-pages nil)
6294 (setq planner-default-page nil)
6298 When you create a task or note, planner will not prompt you for a
6299 date. If you press @key{RET} when prompted for a plan page, it will
6300 accept the default of nil, so no other plan pages will be used. All
6301 of your data will be kept in one file, which can then be easily backed
6304 You can use commands like @command{planner-create-task-from-buffer} to
6305 create tasks, or you can type tasks in manually. You can edit or
6306 delete anything in the page without having to update other files.
6308 @node Bare-Bones Planning with Plan Pages, Tasks on Plan Pages with Some Day Pages, Bare-Bones Planning, Sample Configuration Files
6309 @subsection Bare-Bones Planning with Plan Pages
6311 When you create a task or note, Planner.el can copy this to a plan
6312 page. Plan pages allow you to see an overview of all the data for a
6315 For convenience, the @command{planner-create-task-from-buffer} command
6316 prompts you for a plan page when you create a task.
6320 @node Tasks on Plan Pages with Some Day Pages, Hierarchical Tasks, Bare-Bones Planning with Plan Pages, Sample Configuration Files
6321 @subsection Tasks on Plan Pages with Some Day Pages
6323 If most of your tasks are associated with plan pages but you want to
6324 schedule some tasks on day pages, you can leave day pages on (default)
6325 and then write a function that turns off day pages. For example, the
6326 following code snippet turns off day pages for task creation from
6332 (defun my-planner-create-task-from-buffer ()
6333 "Call `planner-create-task-from-buffer', but without dates."
6335 (let ((planner-use-day-pages nil))
6336 (call-interactively 'planner-create-task-from-buffer)))
6339 @node Hierarchical Tasks, , Tasks on Plan Pages with Some Day Pages, Sample Configuration Files
6340 @subsection Hierarchical Tasks
6341 @cindex hierarchical tasks
6342 @cindex tasks, hierarchy of
6344 You can use @file{allout.el} or other modes for outlining to support
6345 hierarchical tasks in plan pages. No special support is needed.
6347 Tasks created by @command{planner-create-task-from-buffer} and
6348 @code{planner-create-task} are created in the @samp{* Tasks} section.
6349 If @code{planner-add-task-at-end-flag} is non-nil, tasks are added to
6350 the end of the first task block, else they are added to the beginning.
6351 You can then copy and paste tasks into your preferred hierarchy.
6352 Blank lines delimit blocks of tasks upon which automatic sorting is
6355 You can also type in tasks manually. You may find this approach faster
6356 when you are comfortable with planner.
6358 For example, a @file{LearnPlanner} plan page might contain the
6362 * Learn how to use planner.el
6366 #C0 _ Decide where to put Planner
6367 #C0 _ Download the archives
6373 #C0 _ Figure out how to add things to my load path
6374 #C0 _ Actually add it to my load path
6379 If you create tasks for the finest level of detail available at the
6380 moment, you can schedule them onto day pages with @kbd{C-c C-c}
6381 (@command{planner-copy-or-move-task}). Then you can use
6382 @command{planner-jump-to-link} to switch between the day page and the
6386 @node Getting Help, Acknowledgements, Reference Material, Top
6387 @comment node-name, next, previous, up
6388 @chapter Getting Help
6389 @cindex help, getting
6390 @cindex bugs, reporting
6392 After you have read this guide, if you still have questions about
6393 Planner, or if you have bugs to report, there are several places
6396 Planner has an official website at
6397 @url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}. It is a
6400 Bugs may be reported using the Planner Bug-Tracker at
6401 @url{http://gna.org/bugs/?group=planner-el}.
6403 Planner has three mailing lists.
6407 @item planner-el-announce
6408 Low-traffic list for planner-related announcements.
6410 You can join this mailing list (@email{planner-el-announce@@gna.org})
6411 using the subscription form at
6412 @url{http://mail.gna.org/listinfo/planner-el-announce/}. This
6413 mailing list is also available via Gmane (@url{http://gmane.org/}). The
6414 group is called @samp{gmane.emacs.planner.announce}.
6416 @item planner-el-discuss
6417 Discussion, bugfixes, suggestions, tips, and the like for Planner.
6418 This mailing list also includes the content of planner-el-announce.
6420 You can join this mailing list (@email{planner-el-discuss@@gna.org})
6421 using the subscription form at
6422 @url{http://mail.gna.org/listinfo/planner-el-discuss/}. This mailing
6423 list is also available via Gmane with the identifier
6424 @samp{gmane.emacs.planner.general}.
6426 @item planner-el-logs
6427 Log messages for commits made to Planner.
6429 You can join this mailing list (@email{planner-el-logs@@gna.org}) using
6430 the subscription form at
6431 @url{http://mail.gna.org/listinfo/planner-el-logs/}. This mailing list
6432 is also available via Gmane with the identifier
6433 @samp{gmane.emacs.planner.scm}.
6435 @item planner-el-cvs
6436 Generated bug reports for Planner.
6438 You can join this mailing list (@email{planner-el-cvs@@gna.org}) using
6439 the subscription form at
6440 @url{http://mail.gna.org/listinfo/planner-el-cvs/}. This mailing list
6441 is also available via Gmane with the identifier
6442 @samp{gmane.emacs.planner.cvs}.
6446 You can also contact the maintainer of Planner, John Sullivan, at
6447 @email{john@@wjsullivan.net}, but it is better to use the other options.
6449 You can explore the relevant sections of the EmacsWiki.org:
6454 @url{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}
6457 @url{http://www.emacswiki.org/cgi-bin/wiki/MuseMode}
6460 @url{http://www.emacswiki.org/cgi-bin/wiki/RememberMode}
6464 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
6465 contributors are frequently around and willing to answer your
6468 There is an Orkut community called PlannerMode.
6470 For issues relating to this documentation, please contact John
6471 Sullivan at @email{john@@wjsullivan.net}.
6473 @node Acknowledgements, GNU General Public License, Getting Help, Top
6474 @comment node-name, next, previous, up
6475 @chapter Acknowledgements
6484 John Sullivan volunteered to maintain Planner, and Michael Olson passed
6485 the maintainership on to him with the release of Planner 3.41.
6489 Michael Olson, Sacha Chua, and several others from the Planner community
6490 ported Planner to use Muse instead of emacs-wiki. Michael Olson became
6491 the maintainer of Planner.
6495 Damien Elmes handed EmacsWikiMode to Mark Triggs for a short period of
6496 time. Mark Triggs deferred to Sacha Chua as official maintainer of
6497 Planner. Sacha Chua volunteered to maintain RememberMode.
6498 Michael Olson became the maintainer of both emacs-wiki and Muse.
6502 Sacha Chua volunteered to maintain Planner. Damien Elmes
6503 volunteered to maintain EmacsWikiMode.
6507 John Wiegley wrote EmacsWikiMode and Planner.
6511 @cindex contributors
6513 For a complete list of people who have helped out with Planner, please
6514 check out the @file{AUTHORS} file that is included with Planner.
6518 @node GNU General Public License, Concept Index, Acknowledgements, Top
6519 @comment node-name, next, previous, up
6520 @appendix GNU GENERAL PUBLIC LICENSE
6521 @center Version 2, June 1991
6523 @cindex GNU General Public License
6525 @c This file is intended to be included in another file.
6528 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
6529 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
6531 Everyone is permitted to copy and distribute verbatim copies
6532 of this license document, but changing it is not allowed.
6535 @appendixsec Preamble
6537 The licenses for most software are designed to take away your
6538 freedom to share and change it. By contrast, the GNU General Public
6539 License is intended to guarantee your freedom to share and change free
6540 software---to make sure the software is free for all its users. This
6541 General Public License applies to most of the Free Software
6542 Foundation's software and to any other program whose authors commit to
6543 using it. (Some other Free Software Foundation software is covered by
6544 the GNU Library General Public License instead.) You can apply it to
6547 When we speak of free software, we are referring to freedom, not
6548 price. Our General Public Licenses are designed to make sure that you
6549 have the freedom to distribute copies of free software (and charge for
6550 this service if you wish), that you receive source code or can get it
6551 if you want it, that you can change the software or use pieces of it
6552 in new free programs; and that you know you can do these things.
6554 To protect your rights, we need to make restrictions that forbid
6555 anyone to deny you these rights or to ask you to surrender the rights.
6556 These restrictions translate to certain responsibilities for you if you
6557 distribute copies of the software, or if you modify it.
6559 For example, if you distribute copies of such a program, whether
6560 gratis or for a fee, you must give the recipients all the rights that
6561 you have. You must make sure that they, too, receive or can get the
6562 source code. And you must show them these terms so they know their
6565 We protect your rights with two steps: (1) copyright the software, and
6566 (2) offer you this license which gives you legal permission to copy,
6567 distribute and/or modify the software.
6569 Also, for each author's protection and ours, we want to make certain
6570 that everyone understands that there is no warranty for this free
6571 software. If the software is modified by someone else and passed on, we
6572 want its recipients to know that what they have is not the original, so
6573 that any problems introduced by others will not reflect on the original
6574 authors' reputations.
6576 Finally, any free program is threatened constantly by software
6577 patents. We wish to avoid the danger that redistributors of a free
6578 program will individually obtain patent licenses, in effect making the
6579 program proprietary. To prevent this, we have made it clear that any
6580 patent must be licensed for everyone's free use or not licensed at all.
6582 The precise terms and conditions for copying, distribution and
6583 modification follow.
6586 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6589 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
6594 This License applies to any program or other work which contains
6595 a notice placed by the copyright holder saying it may be distributed
6596 under the terms of this General Public License. The ``Program'', below,
6597 refers to any such program or work, and a ``work based on the Program''
6598 means either the Program or any derivative work under copyright law:
6599 that is to say, a work containing the Program or a portion of it,
6600 either verbatim or with modifications and/or translated into another
6601 language. (Hereinafter, translation is included without limitation in
6602 the term ``modification''.) Each licensee is addressed as ``you''.
6604 Activities other than copying, distribution and modification are not
6605 covered by this License; they are outside its scope. The act of
6606 running the Program is not restricted, and the output from the Program
6607 is covered only if its contents constitute a work based on the
6608 Program (independent of having been made by running the Program).
6609 Whether that is true depends on what the Program does.
6612 You may copy and distribute verbatim copies of the Program's
6613 source code as you receive it, in any medium, provided that you
6614 conspicuously and appropriately publish on each copy an appropriate
6615 copyright notice and disclaimer of warranty; keep intact all the
6616 notices that refer to this License and to the absence of any warranty;
6617 and give any other recipients of the Program a copy of this License
6618 along with the Program.
6620 You may charge a fee for the physical act of transferring a copy, and
6621 you may at your option offer warranty protection in exchange for a fee.
6624 You may modify your copy or copies of the Program or any portion
6625 of it, thus forming a work based on the Program, and copy and
6626 distribute such modifications or work under the terms of Section 1
6627 above, provided that you also meet all of these conditions:
6631 You must cause the modified files to carry prominent notices
6632 stating that you changed the files and the date of any change.
6635 You must cause any work that you distribute or publish, that in
6636 whole or in part contains or is derived from the Program or any
6637 part thereof, to be licensed as a whole at no charge to all third
6638 parties under the terms of this License.
6641 If the modified program normally reads commands interactively
6642 when run, you must cause it, when started running for such
6643 interactive use in the most ordinary way, to print or display an
6644 announcement including an appropriate copyright notice and a
6645 notice that there is no warranty (or else, saying that you provide
6646 a warranty) and that users may redistribute the program under
6647 these conditions, and telling the user how to view a copy of this
6648 License. (Exception: if the Program itself is interactive but
6649 does not normally print such an announcement, your work based on
6650 the Program is not required to print an announcement.)
6653 These requirements apply to the modified work as a whole. If
6654 identifiable sections of that work are not derived from the Program,
6655 and can be reasonably considered independent and separate works in
6656 themselves, then this License, and its terms, do not apply to those
6657 sections when you distribute them as separate works. But when you
6658 distribute the same sections as part of a whole which is a work based
6659 on the Program, the distribution of the whole must be on the terms of
6660 this License, whose permissions for other licensees extend to the
6661 entire whole, and thus to each and every part regardless of who wrote it.
6663 Thus, it is not the intent of this section to claim rights or contest
6664 your rights to work written entirely by you; rather, the intent is to
6665 exercise the right to control the distribution of derivative or
6666 collective works based on the Program.
6668 In addition, mere aggregation of another work not based on the Program
6669 with the Program (or with a work based on the Program) on a volume of
6670 a storage or distribution medium does not bring the other work under
6671 the scope of this License.
6674 You may copy and distribute the Program (or a work based on it,
6675 under Section 2) in object code or executable form under the terms of
6676 Sections 1 and 2 above provided that you also do one of the following:
6680 Accompany it with the complete corresponding machine-readable
6681 source code, which must be distributed under the terms of Sections
6682 1 and 2 above on a medium customarily used for software interchange; or,
6685 Accompany it with a written offer, valid for at least three
6686 years, to give any third party, for a charge no more than your
6687 cost of physically performing source distribution, a complete
6688 machine-readable copy of the corresponding source code, to be
6689 distributed under the terms of Sections 1 and 2 above on a medium
6690 customarily used for software interchange; or,
6693 Accompany it with the information you received as to the offer
6694 to distribute corresponding source code. (This alternative is
6695 allowed only for noncommercial distribution and only if you
6696 received the program in object code or executable form with such
6697 an offer, in accord with Subsection b above.)
6700 The source code for a work means the preferred form of the work for
6701 making modifications to it. For an executable work, complete source
6702 code means all the source code for all modules it contains, plus any
6703 associated interface definition files, plus the scripts used to
6704 control compilation and installation of the executable. However, as a
6705 special exception, the source code distributed need not include
6706 anything that is normally distributed (in either source or binary
6707 form) with the major components (compiler, kernel, and so on) of the
6708 operating system on which the executable runs, unless that component
6709 itself accompanies the executable.
6711 If distribution of executable or object code is made by offering
6712 access to copy from a designated place, then offering equivalent
6713 access to copy the source code from the same place counts as
6714 distribution of the source code, even though third parties are not
6715 compelled to copy the source along with the object code.
6718 You may not copy, modify, sublicense, or distribute the Program
6719 except as expressly provided under this License. Any attempt
6720 otherwise to copy, modify, sublicense or distribute the Program is
6721 void, and will automatically terminate your rights under this License.
6722 However, parties who have received copies, or rights, from you under
6723 this License will not have their licenses terminated so long as such
6724 parties remain in full compliance.
6727 You are not required to accept this License, since you have not
6728 signed it. However, nothing else grants you permission to modify or
6729 distribute the Program or its derivative works. These actions are
6730 prohibited by law if you do not accept this License. Therefore, by
6731 modifying or distributing the Program (or any work based on the
6732 Program), you indicate your acceptance of this License to do so, and
6733 all its terms and conditions for copying, distributing or modifying
6734 the Program or works based on it.
6737 Each time you redistribute the Program (or any work based on the
6738 Program), the recipient automatically receives a license from the
6739 original licensor to copy, distribute or modify the Program subject to
6740 these terms and conditions. You may not impose any further
6741 restrictions on the recipients' exercise of the rights granted herein.
6742 You are not responsible for enforcing compliance by third parties to
6746 If, as a consequence of a court judgment or allegation of patent
6747 infringement or for any other reason (not limited to patent issues),
6748 conditions are imposed on you (whether by court order, agreement or
6749 otherwise) that contradict the conditions of this License, they do not
6750 excuse you from the conditions of this License. If you cannot
6751 distribute so as to satisfy simultaneously your obligations under this
6752 License and any other pertinent obligations, then as a consequence you
6753 may not distribute the Program at all. For example, if a patent
6754 license would not permit royalty-free redistribution of the Program by
6755 all those who receive copies directly or indirectly through you, then
6756 the only way you could satisfy both it and this License would be to
6757 refrain entirely from distribution of the Program.
6759 If any portion of this section is held invalid or unenforceable under
6760 any particular circumstance, the balance of the section is intended to
6761 apply and the section as a whole is intended to apply in other
6764 It is not the purpose of this section to induce you to infringe any
6765 patents or other property right claims or to contest validity of any
6766 such claims; this section has the sole purpose of protecting the
6767 integrity of the free software distribution system, which is
6768 implemented by public license practices. Many people have made
6769 generous contributions to the wide range of software distributed
6770 through that system in reliance on consistent application of that
6771 system; it is up to the author/donor to decide if he or she is willing
6772 to distribute software through any other system and a licensee cannot
6775 This section is intended to make thoroughly clear what is believed to
6776 be a consequence of the rest of this License.
6779 If the distribution and/or use of the Program is restricted in
6780 certain countries either by patents or by copyrighted interfaces, the
6781 original copyright holder who places the Program under this License
6782 may add an explicit geographical distribution limitation excluding
6783 those countries, so that distribution is permitted only in or among
6784 countries not thus excluded. In such case, this License incorporates
6785 the limitation as if written in the body of this License.
6788 The Free Software Foundation may publish revised and/or new versions
6789 of the General Public License from time to time. Such new versions will
6790 be similar in spirit to the present version, but may differ in detail to
6791 address new problems or concerns.
6793 Each version is given a distinguishing version number. If the Program
6794 specifies a version number of this License which applies to it and ``any
6795 later version'', you have the option of following the terms and conditions
6796 either of that version or of any later version published by the Free
6797 Software Foundation. If the Program does not specify a version number of
6798 this License, you may choose any version ever published by the Free Software
6802 If you wish to incorporate parts of the Program into other free
6803 programs whose distribution conditions are different, write to the author
6804 to ask for permission. For software which is copyrighted by the Free
6805 Software Foundation, write to the Free Software Foundation; we sometimes
6806 make exceptions for this. Our decision will be guided by the two goals
6807 of preserving the free status of all derivatives of our free software and
6808 of promoting the sharing and reuse of software generally.
6811 @heading NO WARRANTY
6818 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6819 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6820 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6821 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6822 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6823 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6824 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6825 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6826 REPAIR OR CORRECTION.
6829 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
6830 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6831 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6832 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
6833 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
6834 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
6835 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
6836 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
6837 POSSIBILITY OF SUCH DAMAGES.
6841 @heading END OF TERMS AND CONDITIONS
6844 @center END OF TERMS AND CONDITIONS
6848 @appendixsec Appendix: How to Apply These Terms to Your New Programs
6850 If you develop a new program, and you want it to be of the greatest
6851 possible use to the public, the best way to achieve this is to make it
6852 free software which everyone can redistribute and change under these terms.
6854 To do so, attach the following notices to the program. It is safest
6855 to attach them to the start of each source file to most effectively
6856 convey the exclusion of warranty; and each file should have at least
6857 the ``copyright'' line and a pointer to where the full notice is found.
6860 @var{one line to give the program's name and a brief idea of what it does.}
6861 Copyright (C) @var{yyyy} @var{name of author}
6863 This program is free software; you can redistribute it and/or modify
6864 it under the terms of the GNU General Public License as published by
6865 the Free Software Foundation; either version 2 of the License, or
6866 (at your option) any later version.
6868 This program is distributed in the hope that it will be useful,
6869 but WITHOUT ANY WARRANTY; without even the implied warranty of
6870 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6871 GNU General Public License for more details.
6873 You should have received a copy of the GNU General Public License
6874 along with this program; if not, write to the Free Software
6875 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
6878 Also add information on how to contact you by electronic and paper mail.
6880 If the program is interactive, make it output a short notice like this
6881 when it starts in an interactive mode:
6884 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6885 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
6886 This is free software, and you are welcome to redistribute it
6887 under certain conditions; type `show c' for details.
6890 The hypothetical commands @samp{show w} and @samp{show c} should show
6891 the appropriate parts of the General Public License. Of course, the
6892 commands you use may be called something other than @samp{show w} and
6893 @samp{show c}; they could even be mouse-clicks or menu items---whatever
6896 You should also get your employer (if you work as a programmer) or your
6897 school, if any, to sign a ``copyright disclaimer'' for the program, if
6898 necessary. Here is a sample; alter the names:
6901 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
6902 `Gnomovision' (which makes passes at compilers) written by James Hacker.
6904 @var{signature of Ty Coon}, 1 April 1989
6905 Ty Coon, President of Vice
6908 This General Public License does not permit incorporating your program into
6909 proprietary programs. If your program is a subroutine library, you may
6910 consider it more useful to permit linking proprietary applications with the
6911 library. If this is what you want to do, use the GNU Library General
6912 Public License instead of this License.
6914 @node Concept Index, , GNU General Public License, Top
6915 @comment node-name, next, previous, up