Add 2013 to more copyright years
[emacs.git] / doc / misc / remember.texi
blob3a80862d0e710707b9ca3f1a1dc87831a73e4c48
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../../info/remember
4 @settitle Remember Manual
5 @syncodeindex fn cp
6 @c %**end of header
8 @copying
9 This manual is for Remember Mode, version 1.9
11 Copyright @copyright{} 2001, 2004--2005, 2007--2013
12 Free Software Foundation, Inc.
14 @quotation
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
19 and with the Back-Cover Texts as in (a) below.  A copy of the license
20 is included in the section entitled ``GNU Free Documentation License''.
22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23 modify this GNU manual.''
24 @end quotation
25 @end copying
27 @dircategory Emacs misc features
28 @direntry
29 * Remember: (remember).         Simple information manager for Emacs.
30 @end direntry
32 @titlepage
33 @title Guide to Remember Mode
34 @subtitle a simple information manager
35 @subtitle for Emacs and XEmacs
37 @c The following two commands
38 @c start the copyright page.
39 @page
40 @vskip 0pt plus 1filll
41 @insertcopying
42 @end titlepage
44 @contents
46 @ifnottex
47 @node Top, Preface, (dir), (dir)
48 @comment  node-name,  next,  previous,  up
49 @top Remember
51 @insertcopying
52 @end ifnottex
54 @menu
55 * Preface::                     About the documentation.
56 * Introduction::                What is Remember Mode?
57 * Installation::                How to install Remember.
58 * Implementation::              How Remember came into existence.
59 * Quick Start::                 Get started using Remember.
60 * Function Reference::          Interactive functions in remember.el.
61 * Keystrokes::                  Keystrokes bound in Remember Mode.
62 * Backends::                    Backends for saving notes.
63 * GNU Free Documentation License::  The license for this documentation.
64 * Concept Index::               Search for terms.
66 @detailmenu
67  --- The Detailed Node Listing ---
69 Backends
71 * Text File::                   Saving to a text file.
72 * Diary::                       Saving to a Diary file.
73 * Mailbox::                     Saving to a mailbox.
74 * Org::                         Saving to an Org Mode file.
76 @end detailmenu
77 @end menu
79 @node Preface, Introduction, Top, Top
80 @comment  node-name,  next,  previous,  up
81 @chapter Preface
83 This document describes remember-el, which was written by John Wiegley,
84 was once maintained by Sacha Chua, and is now maintained by the Emacs
85 developers.
87 This document is a work in progress, and your contribution will be
88 greatly appreciated.
90 @node Introduction, Installation, Preface, Top
91 @comment  node-name,  next,  previous,  up
92 @chapter Introduction
94 Todo lists, schedules, phone databases... everything we use databases
95 for is really just a way to extend the power of our memory, to be able
96 to remember what our conscious mind may not currently have access to.
98 There are many different databases out there---and good ones---which
99 this mode is not trying to replace.  Rather, it's how that data gets
100 there that's the question.  Most of the time, we just want to say
101 "Remember so-and-so's phone number, or that I have to buy dinner for the
102 cats tonight."  That's the FACT@.  How it's stored is really the
103 computer's problem.  But at this point in time, it's most definitely
104 also the user's problem, and sometimes so laboriously so that people
105 just let data slip, rather than expend the effort to record it.
107 ``Remember'' is a mode for remembering data.  It uses whatever
108 back-end is appropriate to record and correlate the data, but its main
109 intention is to allow you to express as @emph{little} structure as
110 possible up front.  If you later want to express more powerful
111 relationships between your data, or state assumptions that were at
112 first too implicit to be recognized, you can ``study'' the data later
113 and rearrange it.  But the initial ``just remember this'' impulse
114 should be as close to simply throwing the data at Emacs as possible.
116 Have you ever noticed that having a laptop to write on doesn't
117 @emph{actually} increase the amount of quality material that you turn
118 out, in the long run?  Perhaps it's because the time we save
119 electronically in one way, we're losing electronically in another; the
120 tool should never dominate one's focus.  As the mystic Faridu'd-Din
121 `Attar wrote: ``Be occupied as little as possible with things of the
122 outer world but much with things of the inner world; then right action
123 will overcome inaction.''
125 If Emacs could become a more intelligent data store, where brainstorming
126 would focus on the @emph{ideas} involved---rather than the structuring
127 and format of those ideas, or having to stop your current flow of work
128 in order to record them---it would map much more closely to how the mind
129 (well, at least mine) works, and hence would eliminate that very
130 manual-ness which computers from the very beginning have been championed
131 as being able to reduce.
133 @node Installation, Implementation, Introduction, Top
134 @comment  node-name,  next,  previous,  up
135 @chapter Installation
137 Installing Remember Mode is as simple as adding the following lines to
138 your Emacs configuration file (usually @file{~/.emacs.d/init.el} or
139 @file{~/.emacs}).
141 @lisp
142 (add-to-list 'load-path "/path/to/remember")
143 (require 'remember)
144 @end lisp
146 @node Implementation, Quick Start, Installation, Top
147 @comment  node-name,  next,  previous,  up
148 @chapter Implementation
150 Hyperbole, as a data presentation tool, always struck me as being very
151 powerful, but it seemed to require a lot of ``front-end'' work before
152 that data was really available.  The problem with BBDB, or keeping up
153 a Bibl-mode file, is that you have to use different functions to
154 record the data, and it always takes time to stop what you're doing,
155 format the data in the manner expected by that particular data
156 interface, and then resume your work.
158 With ``remember'', you just hit @kbd{M-x remember} (you'd probably
159 want to bind this to an easily accessible keystroke, like @kbd{C-x
160 M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}.
161 It will file the data away for later retrieval, and possibly indexing.
163 Indexing is to data what ``studying'' is in the real world.  What you do
164 when you study (or lucubrate, for some of us) is to realize certain
165 relationships implicit in the data, so that you can make use of those
166 relationships.  Expressing that a certain quote you remembered was a
167 literary quote, and that you want the ability to pull up all quotes of a
168 literary nature, is what studying does.  This is a more labor intensive
169 task than the original remembering of the data, and it's typical in real
170 life to set aside a special period of time for doing this work.
172 ``Remember'' works in the same way.  When you enter data, either by
173 typing it into a buffer, or using the contents of the selected region,
174 it will store that data---unindexed, uninterpreted---in a data pool.
175 It will also try to remember as much context information as possible
176 (any text properties that were set, where you copied it from, when,
177 how, etc).  Later, you can walk through your accumulated set of data
178 (both organized, and unorganized) and easily begin moving things
179 around, and making annotations that will express the full meaning of
180 that data, as far as you know it.
182 Obviously this latter stage is more user-interface intensive, and it
183 would be nice if ``remember'' could do it as elegantly as possible,
184 rather than requiring a billion keystrokes to reorganize your
185 hierarchy.  Well, as the future arrives, hopefully experience and user
186 feedback will help to make this as intuitive a tool as possible.
188 @node Quick Start, Function Reference, Implementation, Top
189 @comment  node-name,  next,  previous,  up
190 @chapter Quick Start
192 @itemize
194 @item
195 Load @file{remember.el}.
197 @item
198 Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be
199 displayed.
201 @item
202 Type in what you want to remember. The first line will be treated as
203 the headline, and the rest of the buffer will contain the body of the
204 note.
206 @item
207 Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close
208 the @samp{*Remember*} buffer.
209 @end itemize
211 By default, @code{remember-finalize} saves the note in @file{~/.notes}.
212 You can edit it now to see the remembered and timestamped note. You
213 can edit this file however you want. New entries will always be added
214 to the end.
216 To remember a region of text, use the universal prefix. @kbd{C-u M-x
217 remember} displays a @samp{*Remember*} buffer with the region as the
218 initial contents.
220 As a simple beginning, you can start by using the Text File backend,
221 keeping your @file{~/.notes} file in outline-mode format, with a final
222 entry called @samp{* Raw data}. Remembered data will be added to the
223 end of the file. Every so often, you can move the data that gets
224 appended there into other files, or reorganize your document.
226 You can also store remembered data in other backends.
227 (@pxref{Backends})
229 Here is one way to map the remember functions in your @file{.emacs} to
230 very accessible keystrokes facilities using the mode:
232 @lisp
233 (autoload 'remember ``remember'' nil t)
234 (autoload 'remember-region ``remember'' nil t)
236 (define-key global-map (kbd "<f9> r") 'remember)
237 (define-key global-map (kbd "<f9> R") 'remember-region)
238 @end lisp
240 By default, remember uses the first annotation returned by
241 @code{remember-annotation-functions}. To include all of the annotations,
242 set @code{remember-run-all-annotation-functions-flag} to non-nil.
244 @defopt remember-run-all-annotation-functions-flag
245 Non-nil means use all annotations returned by
246 @code{remember-annotation-functions}.
247 @end defopt
249 You can write custom functions that use a different set of
250 remember-annotation-functions. For example:
252 @lisp
253 (defun my/remember-with-filename ()
254  "Always use the filename."
255  (interactive)
256  (let ((remember-annotation-functions '(buffer-file-name)))
257   (call-interactively 'remember)))
258 @end lisp
260 @node Function Reference, Keystrokes, Quick Start, Top
261 @comment  node-name,  next,  previous,  up
262 @chapter Function Reference
264 @file{remember.el} defines the following interactive functions:
266 @defun remember initial
267 Remember an arbitrary piece of data. With a prefix, it will use the
268 region as @var{initial}.
269 @end defun
271 @defun remember-region beg end
272 If called from within the remember buffer, @var{beg} and @var{end} are
273 ignored, and the entire buffer will be remembered.  If called from any
274 other buffer, that region, plus any context information specific to
275 that region, will be remembered.
276 @end defun
278 @defun remember-clipboard
279 Remember the contents of the current clipboard.  This is most useful
280 for remembering things from Netscape or other X Windows applications.
281 @end defun
283 @defun remember-finalize
284 Remember the contents of the current buffer.
285 @end defun
287 @defun remember-mode
288 This enters the major mode for output from @command{remember}.  This
289 buffer is used to collect data that you want remember.  Just hit
290 @kbd{C-c C-c} when you're done entering, and it will go ahead and file
291 the data for latter retrieval, and possible indexing.
292 @end defun
294 @node Keystrokes, Backends, Function Reference, Top
295 @comment  node-name,  next,  previous,  up
296 @chapter Keystroke Reference
298 @file{remember.el} defines the following keybindings by default:
300 @table @kbd
302 @item C-c C-c (`remember-finalize')
303 Remember the contents of the current buffer.
305 @item C-c C-k (`remember-destroy')
306 Destroy the current *Remember* buffer.
308 @item C-x C-s (`remember-finalize')
309 Remember the contents of the current buffer.
311 @end table
313 @node Backends, GNU Free Documentation License, Keystrokes, Top
314 @comment  node-name,  next,  previous,  up
315 @chapter Backends
317 You can save remembered notes to a variety of backends.
319 @menu
320 * Text File::                   Saving to a text file.
321 * Diary::                       Saving to a Diary file.
322 * Mailbox::                     Saving to a mailbox.
323 * Org::                         Saving to an Org Mode file.
324 @end menu
326 @node Text File, Diary, Backends, Backends
327 @comment  node-name,  next,  previous,  up
328 @section Saving to a Text File
329 @cindex text file, saving to
331 @subheading Insinuation
333 @lisp
334 (setq remember-handler-functions '(remember-append-to-file))
335 @end lisp
337 @subheading Options
339 @defopt remember-data-file
340 The file in which to store unprocessed data.
341 @end defopt
343 @defopt remember-leader-text
344 The text used to begin each remember item.
345 @end defopt
347 @node Diary, Mailbox, Text File, Backends
348 @comment  node-name,  next,  previous,  up
349 @section Saving to a Diary file
350 @cindex diary, integration
352 @subheading Insinuation
354 @lisp
355 (add-to-list 'remember-handler-functions 'remember-diary-extract-entries)
356 @end lisp
358 @subheading Options
360 @defopt remember-diary-file
361 File for extracted diary entries.
362 If this is nil, then @code{diary-file} will be used instead."
363 @end defopt
365 @node Mailbox, Org, Diary, Backends
366 @comment  node-name,  next,  previous,  up
367 @section Saving to a Mailbox
368 @cindex mailbox, saving to
370 @subheading Insinuation
372 @lisp
373 (add-to-list 'remember-handler-functions 'remember-store-in-mailbox)
374 @end lisp
376 @subheading Options
378 @defopt remember-mailbox
379 The file in which to store remember data as mail.
380 @end defopt
382 @defopt remember-default-priority
383 The default priority for remembered mail messages.
384 @end defopt
386 @node Org, , Mailbox, Backends
387 @comment  node-name,  next,  previous,  up
388 @section Saving to an Org Mode file
389 @cindex org mode, integration
391 @ignore
392 From org.texi:
393 Up to version 6.36 Org used a special setup
394 for @file{remember.el}.  @file{org-remember.el} is still part of Org mode for
395 backward compatibility with existing setups.  You can find the documentation
396 for org-remember at @url{http://orgmode.org/org-remember.pdf}.
397 @end ignore
398 For instructions on how to integrate Remember with Org Mode,
399 consult @ref{Capture, , , org}.
401 @node GNU Free Documentation License, Concept Index, Backends, Top
402 @appendix GNU Free Documentation License
403 @include doclicense.texi
405 @node Concept Index,  , GNU Free Documentation License, Top
406 @comment  node-name,  next,  previous,  up
407 @unnumbered Index
409 @printindex cp
411 @bye