Document through planner-publish.el.
[planner-el.git] / README
blobfe3840a95773efcb23c5f01b4c78554328b5f3fc
2 This is the README file for Planner.
4 Synopsis
5 ========
7 Planner is an organizer and day planner for Emacs.  It helps you keep
8 track of your pending and completed tasks, daily schedule, dates to
9 remember, notes and inspirations.  It is a powerful tool not only for
10 managing your time and productivity, but also for keeping within easy
11 keystroke reach all of the information you need to be productive.  It
12 can even publish reports charting your work for your personal web
13 page, your conscience, or your soon-to-be-impressed boss.
15 In fact, because it uses as its building blocks simple plain-text
16 files, it is an incredibly modular and flexible tool capable of
17 shaping and handling your personal information in ways whose variety
18 is limited only by your imagination.  Because of this, Planner has a
19 very active and generous community who regularly share their
20 innovations with each other.  Many of these modules and extensions are
21 included.
23 License
24 =======
26 Planner is free software; you can redistribute it and/or modify it
27 under the terms of the GNU General Public License as published by the
28 Free Software Foundation; either version 2, or (at your option) any
29 later version.
31 Planner is distributed in the hope that it will be useful, but WITHOUT
32 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
33 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
34 for more details.
36 You should have received a copy of the GNU General Public License
37 along with Planner; see the file COPYING.  If not, write to the Free
38 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
39 02110-1301, USA.
41 Directory contents
42 ==================
44 The directory structure is as follows.
46 top level :: Planner source code and the documentation
47              (planner-el.texi).
49 contrib :: Files that are not a part of Planner proper, but are useful
50            enough to be bundled with Planner.
52 scripts :: Scripts that are used when compiling Planner.
54 Getting started
55 ===============
57 Compilation
58 -----------
60 This is an optional step, since Emacs Lisp source code does not
61 necessarily have to be byte-compiled.  It will yield a speed increase,
62 though.
64 A working copy of Emacs or XEmacs is needed in order to compile
65 Planner.  By default, the program that is installed with the name
66 `emacs' will be used.
68 If you want to use the `xemacs' binary to perform the compilation, you
69 would need to edit `Makefile.defs' in the top-level directory as
70 follows.  You can put either a full path to an Emacs or XEmacs binary
71 or just the command name, as long as it is in the PATH.
73 EMACS    = xemacs
74 SITEFLAG = -no-site-file
76 In order for Planner to be byte-compiled properly, you will need to
77 specify the paths to Muse and other external software programs in
78 `scripts/planner-build.el'.  If a file fails to be byte-compiled, only
79 its source will be installed.
81 Running `make' should compile the Planner source files in the `lisp'
82 directory.
84 Installation
85 ------------
87 Planner may be installed into your file hierarchy by doing the
88 following.
90 Edit the `Makefile.defs' file so that ELISPDIR points to where you
91 want the source and compiled Planner files to be installed and INFODIR
92 indicates where to put the Planner manual.  Of course, you will want
93 to edit EMACS and SITEFLAG as shown in the Compilation section if you
94 are using XEmacs.
96 If you are installing Planner on a Debian system, you might want to
97 change the value of INSTALLINFO as specified in `Makefile.defs'.
99 If you wish to install Planner to different locations than the
100 defaults specify, edit `Makefile.defs' accordingly.
102 Run `make' as a normal user.
104 Run `make install' as the root user if you have chosen installation
105 locations that require this.
107 Insinuation
108 -----------
110 Two things need to happen in order for Planner to be usable with your
111 version of Emacs or XEmacs.
113  1. The location of the Planner directory needs to be added to the load
114     path so that your variant of Emacs can find it.
116  2. You need to load whichever Planner files you wish to make use of.
118 A quick example that accomplishes both of these follows.
120 ;; Add this to your .emacs or .xemacs/init.el file.
121 (add-to-list 'load-path "/path/to/planner")
122 (require 'planner)
124 Documentation
125 -------------
127 The Planner manual may be generated by running `make doc'.
129 It will produce two files: an Info file called `planner-el.info' and
130 an HTML document called `planner-el.html'.
132 This manual is also available online in several forms.
134  - PDF: http://www.mwolson.org/static/doc/planner.pdf
135  - HTML (single file): http://www.mwolson.org/static/doc/planner.html
136  - HTML (multiple files): http://www.mwolson.org/static/doc/planner/
138 Further Documentation
139 =====================
141 Planner has an official website at http://www.plannerlove.com/.  It is
142 a collaborative wiki.
144 Bugs may be reported using the Planner Bug-Tracker at
145 https://gna.org/bugs/?group=planner-el.
147 A mailing list for Planner and some related software exists; consult
148 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
149 on joining it or viewing its contents.